@tpsdev-ai/flair 0.20.1 → 0.21.0

package/dist/deploy.js

@@ -187,7 +187,7 @@ function resolveHarperBin(packageRoot) {
 export function buildHarperDeployArgs(opts, url, project) {
     const deploymentTimeoutMs = opts.deploymentTimeoutMs ?? DEFAULT_DEPLOYMENT_TIMEOUT_MS;
     const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
-    return [
+    const args = [
         "deploy",
         `target=${url}`,
         `project=${project}`,
@@ -196,26 +196,108 @@ export function buildHarperDeployArgs(opts, url, project) {
         `deployment_timeout=${deploymentTimeoutMs}`,
         `install_timeout=${installTimeoutMs}`,
     ];
+    // --ignore-replication-errors escape hatch. Only appended when
+    // set — omitted entirely otherwise, so this is a no-op for every existing
+    // caller/test that doesn't pass it.
+    if (opts.ignoreReplicationErrors) {
+        args.push("ignore_replication_errors=true");
+    }
+    return args;
 }
-function spawnHarper(bin, args, cwd, env) {
+// Flaky-peer-replication resilience defaults. See DeployOptions
+// for the full incident writeup this closes.
+export const DEFAULT_DEPLOY_RETRIES = 2;
+export const DEPLOY_RETRY_BACKOFF_MS = [5_000, 10_000];
+// The signature of a Fabric PEER-REPLICATION failure specifically — harper
+// deploys fine to the origin node, but pushing the component to a peer
+// fails, e.g.:
+//   "Component 'flair' was deployed on the origin node but failed to
+//    replicate to 1 of 1 peer node(s): ... (Error: Connection closed 1006)"
+// This is the CORRECTNESS-CRITICAL part of the fix: matching this pattern
+// (and ONLY this pattern) is what lets us retry a known flake while still
+// failing fast on a real deploy failure (bad package, auth, missing files —
+// none of which mention peer replication and must never be retried).
+// Literal regex, no interpolation.
+export const REPLICATION_FAILURE_RE = /failed to replicate to \d+ (of \d+ )?peer|connection closed\s+1006|ignore_replication_errors/i;
+// Tee-style capture: streams harper's stdout/stderr to the user in real time
+// (unchanged UX — a multi-minute deploy needs live progress, not a black
+// box) while ALSO buffering the combined text so the caller can
+// pattern-match REPLICATION_FAILURE_RE against it after exit. This replaces
+// the previous stdio:"inherit" passthrough, which gave no way to inspect
+// harper's output. stdin stays "inherit" — harper's deploy never reads
+// from it, so there's nothing to tee there.
+function spawnHarperCaptured(bin, args, cwd, env) {
     return new Promise((resolveP, rejectP) => {
         const p = spawn(process.execPath, [bin, ...args], {
             cwd,
-            stdio: "inherit",
+            stdio: ["inherit", "pipe", "pipe"],
             env,
         });
-        p.on("error", rejectP);
-        p.on("exit", (code) => {
-            if (code === 0)
-                resolveP();
-            else
-                rejectP(new Error(`harper deploy exited with code ${code}`));
+        const chunks = [];
+        p.stdout?.on("data", (d) => {
+            process.stdout.write(d);
+            chunks.push(d.toString("utf8"));
+        });
+        p.stderr?.on("data", (d) => {
+            process.stderr.write(d);
+            chunks.push(d.toString("utf8"));
         });
+        p.on("error", rejectP);
+        p.on("exit", (code) => resolveP({ code, output: chunks.join("") }));
     });
 }
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// Runs `harper deploy`, retrying ONLY on the flaky peer-replication failure
+// signature (REPLICATION_FAILURE_RE) — the real incident this closes: the
+// origin deployed fine, replication to a peer failed with a transient
+// "Connection closed 1006", and a bare manual retry cleared it with no
+// other change. This re-runs the FULL harper deploy (prepare/install/
+// replicate), not just a peer-only re-push — wasteful, but it's exactly
+// what worked by hand, and harper's CLI has no "retry replication only"
+// entry point. Any other failure (bad package, auth, missing files, ...)
+// is never retried — it fails fast, same as before this change.
+async function runHarperDeploy(bin, args, cwd, env, opts) {
+    const maxRetries = opts.deployRetries ?? DEFAULT_DEPLOY_RETRIES;
+    const backoff = opts.deployRetryBackoffMs ?? DEPLOY_RETRY_BACKOFF_MS;
+    const totalAttempts = Math.max(1, maxRetries + 1);
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        const { code, output } = await spawnHarperCaptured(bin, args, cwd, env);
+        if (code === 0)
+            return { replicationWarning: false };
+        const isReplicationFailure = REPLICATION_FAILURE_RE.test(output);
+        const isLastAttempt = attempt === totalAttempts;
+        if (isReplicationFailure && !isLastAttempt) {
+            const waitMs = backoff[Math.min(attempt - 1, backoff.length - 1)];
+            // Self-healing must be visible, never silent — console.warn directly
+            // (not gated behind onProgress, which some callers like
+            // fabric-upgrade.ts don't wire up) so this is loud regardless of caller.
+            console.warn(`⚠ flair deploy: replication flake on attempt ${attempt}/${totalAttempts} ` +
+                `(harper deploy exited ${code}, peer-replication signature matched) — ` +
+                `retrying in ${Math.round(waitMs / 1000)}s...`);
+            opts.onProgress?.(`replication flake on attempt ${attempt}/${totalAttempts} — retrying in ${Math.round(waitMs / 1000)}s...`);
+            await sleep(waitMs);
+            continue;
+        }
+        if (isReplicationFailure && opts.ignoreReplicationErrors) {
+            console.warn(`⚠ flair deploy: peer replication still failing after ${attempt} attempt(s), ` +
+                `but --ignore-replication-errors is set — treating this as a WARNED SUCCESS ` +
+                `(deployed to the origin node only; the peer will need to catch up via normal ` +
+                `federation sync or a later deploy).`);
+            opts.onProgress?.(`WARNING: proceeding origin-only — peer replication did not complete after ${attempt} attempt(s)`);
+            return { replicationWarning: true };
+        }
+        if (isReplicationFailure) {
+            throw new Error(`harper deploy exited with code ${code}: peer replication failed after ${attempt} attempt(s) ` +
+                `(retries exhausted). Pass --ignore-replication-errors to accept an origin-only deploy, ` +
+                `or re-run once the peer link recovers.`);
+        }
+        throw new Error(`harper deploy exited with code ${code}`);
+    }
+    // Unreachable — the loop always returns or throws — but keeps TS happy.
+    throw new Error("harper deploy: exhausted retry loop without resolving");
+}
 // A single reachability probe against the served (REST) base URL. Harper
 // restarts the process after every deploy, so the endpoint FLAPS for a bit —
 // connection refused / reset / DNS blips are all EXPECTED right after
@@ -321,7 +403,7 @@ export async function deploy(opts) {
         CLI_TARGET_USERNAME: opts.fabricUser,
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
-    await spawnHarper(harperBin, args, packageRoot, childEnv);
+    const { replicationWarning } = await runHarperDeploy(harperBin, args, packageRoot, childEnv, opts);
     // harper can print "Successfully deployed" for a component that isn't
     // actually serving anything (the incident this closes: an empty deploy,
     // reported success, /Memory 404ing in prod). Verify by curling the served
@@ -337,5 +419,5 @@ export async function deploy(opts) {
             onProgress: opts.onProgress,
         });
     }
-    return { url, project, version, packageRoot, dryRun: false };
+    return { url, project, version, packageRoot, dryRun: false, replicationWarning };
 }

package/dist/doctor-client.js

@@ -0,0 +1,312 @@
+// ─── Doctor: client integration checks (flair#588) ──────────────────────────────
+//
+// `flair doctor` diagnosed the SERVER side only (Harper port, keys, config,
+// embeddings, data dir). It had zero visibility into whether the CLIENT
+// integration — the MCP wiring an agent like Claude Code actually uses — is
+// working. A real incident found users with partial setups (MCP block wired
+// but no CLAUDE.md line; or no SessionStart hook) that silently no-op, with
+// no way to tell "is Flair working for my agent?" short of an incident.
+//
+// This module is pure filesystem logic (no network, no crypto) so it's fast
+// and fully unit-testable in isolation — mirrors test/unit/client-wiring.test.ts's
+// technique of overriding process.env.HOME to a temp dir. The two
+// network-dependent checks (reachability + agent registration) live in
+// src/cli.ts alongside authFetch/resolveKeyPath, which they reuse.
+//
+// Every read here is try/catch-wrapped: a missing or malformed config file is
+// "not present", never a thrown error — doctor must never crash or hang on a
+// broken client config.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { clientConfigPath } from "./install/clients.js";
+// The exact substring `flair init` writes into CLAUDE.md (src/cli.ts, the
+// `init` action) and that the doctor check + fix both key off of.
+export const CLAUDE_MD_BOOTSTRAP_MARKER = "mcp__flair__bootstrap";
+const CLAUDE_MD_BOOTSTRAP_LINE = "At the start of every session, run mcp__flair__bootstrap before responding.";
+// The exact substring identifying a Flair SessionStart hook command (see
+// docs/mcp-clients.md "Auto-recall on session start").
+export const SESSION_START_HOOK_MARKER = "flair-session-start";
+// ── shared helpers ──────────────────────────────────────────────────────────
+/**
+ * Run `fn` with process.env.HOME temporarily pointed at `homeDir`, then
+ * restore it. clientConfigPath() (src/install/clients.ts) resolves the home
+ * dir via HOME/USERPROFILE at call time (not cached), so this lets us reuse
+ * that single source of truth for per-client config paths while keeping
+ * doctor-client's own functions parameterized by an explicit homeDir for
+ * tests — no test ever touches the real ~/.claude.json etc. The override is
+ * synchronous and restored before this function returns, so it's safe even
+ * though process.env is process-global.
+ */
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function readTextFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the Flair MCP server block from `clientId`'s config file. `present`
+ * is true only when the block exists AND both FLAIR_AGENT_ID and FLAIR_URL
+ * are set (non-empty) — a half-wired block (e.g. block present, env missing)
+ * counts as absent for the pass/fail check, but agentId/flairUrl are still
+ * returned when partially found so callers can use whatever is known.
+ */
+export function readClientMcpBlock(clientId, homeDir) {
+    const configPath = withHome(homeDir, () => clientConfigPath(clientId));
+    return clientId === "codex" ? readCodexFlairBlock(configPath) : readJsonFlairBlock(configPath);
+}
+function readJsonFlairBlock(configPath) {
+    const raw = readTextFile(configPath);
+    if (!raw || !raw.trim())
+        return { present: false, configPath };
+    try {
+        const config = JSON.parse(raw);
+        const flair = config?.mcpServers?.flair;
+        if (!flair || typeof flair !== "object")
+            return { present: false, configPath };
+        const agentId = typeof flair.env?.FLAIR_AGENT_ID === "string" && flair.env.FLAIR_AGENT_ID ? flair.env.FLAIR_AGENT_ID : undefined;
+        const flairUrl = typeof flair.env?.FLAIR_URL === "string" && flair.env.FLAIR_URL ? flair.env.FLAIR_URL : undefined;
+        return { present: !!agentId && !!flairUrl, configPath, agentId, flairUrl };
+    }
+    catch {
+        // Malformed JSON — treat as "not present", never throw.
+        return { present: false, configPath };
+    }
+}
+/**
+ * Codex's config is TOML, and this repo carries no TOML parser (see the
+ * comment on _wireCodex in src/install/clients.ts) — so this is a lightweight
+ * string scan, matching the exact shape _wireCodex/tomlSnippet() produce:
+ *
+ *   [mcp_servers.flair]
+ *   command = "npx"
+ *   args = ["-y", "@tpsdev-ai/flair-mcp"]
+ *
+ *   [mcp_servers.flair.env]
+ *   FLAIR_AGENT_ID = "..."
+ *   FLAIR_URL = "..."
+ *
+ * We locate the `[mcp_servers.flair]` header, then collect lines until a
+ * header that is NOT part of this table (i.e. doesn't start with
+ * "[mcp_servers.flair") — deliberately does NOT stop at the nested
+ * `[mcp_servers.flair.env]` sub-table, since that's where the two env keys
+ * actually live.
+ */
+function readCodexFlairBlock(configPath) {
+    const raw = readTextFile(configPath);
+    if (!raw)
+        return { present: false, configPath };
+    const scanned = scanCodexFlairBlock(raw);
+    return { present: scanned.present, configPath, agentId: scanned.agentId, flairUrl: scanned.flairUrl };
+}
+function scanCodexFlairBlock(raw) {
+    const startMatch = raw.match(/^\[mcp_servers\.flair\]\s*$/m);
+    if (!startMatch || startMatch.index === undefined)
+        return { present: false };
+    const rest = raw.slice(startMatch.index);
+    const lines = rest.split("\n");
+    const blockLines = [lines[0]];
+    for (let i = 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith("[") && !trimmed.startsWith("[mcp_servers.flair"))
+            break;
+        blockLines.push(lines[i]);
+    }
+    const block = blockLines.join("\n");
+    const agentMatch = block.match(/^\s*FLAIR_AGENT_ID\s*=\s*"([^"]*)"/m);
+    const urlMatch = block.match(/^\s*FLAIR_URL\s*=\s*"([^"]*)"/m);
+    const agentId = agentMatch?.[1] || undefined;
+    const flairUrl = urlMatch?.[1] || undefined;
+    return { present: !!agentId && !!flairUrl, agentId, flairUrl };
+}
+/**
+ * Pass when EITHER the project-scoped `${cwd}/CLAUDE.md` or the user-level
+ * `~/.claude/CLAUDE.md` contains the bootstrap marker — Claude Code loads
+ * both. Checks cwd first (the convention docs/claude-code.md documents and
+ * what `flair init` tells users to edit).
+ */
+export function checkClaudeMdBootstrap(cwd, homeDir) {
+    const cwdPath = join(cwd, "CLAUDE.md");
+    const cwdContent = readTextFile(cwdPath);
+    if (cwdContent && cwdContent.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+        return { present: true, path: cwdPath };
+    }
+    const homePath = join(homeDir, ".claude", "CLAUDE.md");
+    const homeContent = readTextFile(homePath);
+    if (homeContent && homeContent.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+        return { present: true, path: homePath };
+    }
+    return { present: false, path: null };
+}
+/**
+ * Append the bootstrap instruction to `${cwd}/CLAUDE.md` (creating it if
+ * absent). Idempotent — safe to call twice; a second call is a no-op that
+ * still reports ok:true.
+ */
+export function fixClaudeMdBootstrap(cwd) {
+    const path = join(cwd, "CLAUDE.md");
+    try {
+        const existing = readTextFile(path) ?? "";
+        if (existing.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+            return { ok: true, path, message: `already present in ${path}` };
+        }
+        const separator = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        const block = `${separator}## Flair memory\n\n${CLAUDE_MD_BOOTSTRAP_LINE}\n`;
+        writeFileSync(path, existing + block);
+        return { ok: true, path, message: `added bootstrap instruction to ${path}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, message: `could not write ${path}: ${reason}` };
+    }
+}
+/**
+ * Pass when ~/.claude/settings.json exists, parses as JSON, and ANY hook
+ * command anywhere under hooks.SessionStart[*].hooks[*].command contains the
+ * flair-session-start marker (see docs/mcp-clients.md for the exact shape).
+ */
+export function checkSessionStartHook(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    const raw = readTextFile(path);
+    if (!raw || !raw.trim())
+        return { present: false, path };
+    try {
+        const config = JSON.parse(raw);
+        const groups = config?.hooks?.SessionStart;
+        if (!Array.isArray(groups))
+            return { present: false, path };
+        for (const group of groups) {
+            const hooks = group?.hooks;
+            if (!Array.isArray(hooks))
+                continue;
+            for (const hook of hooks) {
+                if (typeof hook?.command === "string" && hook.command.includes(SESSION_START_HOOK_MARKER)) {
+                    return { present: true, path };
+                }
+            }
+        }
+        return { present: false, path };
+    }
+    catch {
+        return { present: false, path };
+    }
+}
+/**
+ * Merge-safe insert of a Flair SessionStart hook group into
+ * ~/.claude/settings.json — creates the file/array if absent, preserves any
+ * other existing hooks/keys (read-parse-merge-write, mirroring wireJsonMcp's
+ * merge safety in src/install/clients.ts; never a blind overwrite). Dedupes:
+ * a no-op (ok:true) if a matching hook is already present, so it's safe to
+ * call twice.
+ */
+export function fixSessionStartHook(homeDir, agentId) {
+    const path = join(homeDir, ".claude", "settings.json");
+    if (!agentId) {
+        return {
+            ok: false,
+            path,
+            message: "no agent id known — pass --agent <id> (or set FLAIR_AGENT_ID) so doctor knows which agent to wire the hook to",
+        };
+    }
+    try {
+        let config = {};
+        const raw = readTextFile(path);
+        if (raw && raw.trim())
+            config = JSON.parse(raw);
+        config.hooks = config.hooks && typeof config.hooks === "object" ? config.hooks : {};
+        config.hooks.SessionStart = Array.isArray(config.hooks.SessionStart) ? config.hooks.SessionStart : [];
+        const alreadyPresent = config.hooks.SessionStart.some((group) => Array.isArray(group?.hooks) &&
+            group.hooks.some((h) => typeof h?.command === "string" && h.command.includes(SESSION_START_HOOK_MARKER)));
+        if (alreadyPresent) {
+            return { ok: true, path, message: `already present in ${path}` };
+        }
+        config.hooks.SessionStart.push({
+            hooks: [
+                {
+                    type: "command",
+                    command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                },
+            ],
+        });
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, path, message: `added SessionStart hook to ${path} (agent '${agentId}')` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, message: `could not write ${path}: ${reason}` };
+    }
+}
+function indentLines(s) {
+    return s
+        .split("\n")
+        .map((l) => `     ${l}`)
+        .join("\n");
+}
+/**
+ * Apply-or-report for the CLAUDE.md bootstrap leg. Idempotent: a second call
+ * after the line is present (whether from a prior call or already there)
+ * reports ok:true, applied:false — safe to call on every `flair init`.
+ */
+export function applyOrReportClaudeMdBootstrap(cwd, homeDir, skip) {
+    const existing = checkClaudeMdBootstrap(cwd, homeDir);
+    if (existing.present) {
+        return { applied: false, ok: true, message: `CLAUDE.md already has the bootstrap instruction (${existing.path})` };
+    }
+    const hint = `Add to your CLAUDE.md:\n${indentLines(CLAUDE_MD_BOOTSTRAP_LINE)}`;
+    if (skip) {
+        return { applied: false, ok: false, message: "CLAUDE.md bootstrap instruction skipped (--skip-claude-md)", hint };
+    }
+    const fix = fixClaudeMdBootstrap(cwd);
+    return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
+}
+function sessionStartHookHint(agentId, path) {
+    const snippet = {
+        hooks: {
+            SessionStart: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    return `Add this to ${path}:\n${indentLines(JSON.stringify(snippet, null, 2))}`;
+}
+/**
+ * Apply-or-report for the SessionStart hook leg. Idempotent: a second call
+ * after the hook is present (whether from a prior call or already there)
+ * reports ok:true, applied:false — safe to call on every `flair init`.
+ */
+export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
+    const existing = checkSessionStartHook(homeDir);
+    if (existing.present) {
+        return { applied: false, ok: true, message: `SessionStart hook already wired in ${existing.path}` };
+    }
+    const hint = sessionStartHookHint(agentId, existing.path);
+    if (skip) {
+        return { applied: false, ok: false, message: "SessionStart hook skipped (--skip-hook)", hint };
+    }
+    const fix = fixSessionStartHook(homeDir, agentId);
+    return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
+}

package/dist/install/clients.js

@@ -179,6 +179,24 @@ function geminiConfigPath() {
 function codexConfigPath() {
     return join(resolveHome(), ".codex", "config.toml");
 }
+/**
+ * Single dispatcher for "where does this client's MCP config live" — used by
+ * `flair doctor`'s client-integration checks (flair#588) to read the config
+ * without duplicating the per-client path logic that already lives here.
+ * Additive only: does not change existing wire/detect behavior.
+ */
+export function clientConfigPath(id) {
+    switch (id) {
+        case "claude-code":
+            return join(resolveHome(), ".claude.json");
+        case "codex":
+            return codexConfigPath();
+        case "gemini":
+            return geminiConfigPath();
+        case "cursor":
+            return cursorConfigPath();
+    }
+}
 // ---- Internal wiring functions --------------------------------------------------
 //
 // Claude Code wiring lives inline in src/cli.ts (it writes ~/.claude.json, the

package/dist/rem/restore.js

@@ -213,7 +213,7 @@ export async function applySnapshot(opts) {
     //    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.
+    //    failures that wash out numerically.
     if (opts.verifyPostRestore !== false) {
         try {
             const verifyMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));

package/dist/resources/Admin.js

@@ -7,7 +7,7 @@ import { allowAdmin } from "./agent-auth.js";
  * they hit a 404 and assume the admin UI is broken. The dashboard is the
  * canonical landing surface; redirect there.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): the /Admin* pathname
+ * allowRead()=allowAdmin (defense-in-depth): the /Admin* pathname
  * gate in auth-middleware.ts only 401s when there's NO Authorization header
  * at all (or Basic creds don't resolve to a real user) — a validly-verified
  * TPS-Ed25519 agent that is NOT an admin, or a valid-but-non-super_user Basic

package/dist/resources/AdminConnectors.js

@@ -4,7 +4,7 @@ import { allowAdmin } from "./agent-auth.js";
 /**
  * GET /AdminConnectors — OAuth clients and active sessions.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts.
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts.
  */
 export class AdminConnectors extends Resource {
     async allowRead() {

package/dist/resources/AdminDashboard.js

@@ -4,7 +4,7 @@ import { allowAdmin } from "./agent-auth.js";
 /**
  * GET /AdminDashboard — admin home page with system overview.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts for why
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts for why
  * this closes a real gap, not just belt-and-suspenders — a verified
  * non-admin agent could otherwise read full instance stats (principal/agent/
  * memory/relationship counts) with no admin check at all.

package/dist/resources/AdminIdp.js

@@ -4,7 +4,7 @@ import { allowAdmin } from "./agent-auth.js";
 /**
  * GET /AdminIdp — enterprise IdP configuration management.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts.
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts.
  */
 export class AdminIdp extends Resource {
     async allowRead() {

package/dist/resources/AdminInstance.js

@@ -85,7 +85,7 @@ function resolveVersion() {
 /**
  * GET /AdminInstance — instance info, public key, version.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts.
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts.
  */
 export class AdminInstance extends Resource {
     async allowRead() {

package/dist/resources/AdminMemory.js

@@ -21,7 +21,7 @@ import { allowAdmin } from "./agent-auth.js";
  * makes that legible: every memory shows where it came from, what it derived
  * from, what it superseded, and which peer it synced from.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts — this
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts — this
  * page surfaces full memory content across ALL agents, so the gap it closes
  * matters more here than on the other Admin* pages.
  */
@@ -31,7 +31,7 @@ export class AdminMemory extends Resource {
     }
     async get() {
         // Harper v5 does not populate this.request on Resource subclasses —
-        // getContext() is the only reliable path (ops-sal4: the previous
+        // getContext() is the only reliable path (the previous
         // `(this as any).request` read was always undefined, so query params
         // (?id=, ?q=, ?subject=, ?limit=) were always ignored).
         const ctx = this.getContext?.();

package/dist/resources/AdminPrincipals.js

@@ -4,7 +4,7 @@ import { allowAdmin } from "./agent-auth.js";
 /**
  * GET /AdminPrincipals — list all principals with kind, trust, status.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts.
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts.
  */
 export class AdminPrincipals extends Resource {
     async allowRead() {

package/dist/resources/Agent.js

@@ -1,5 +1,6 @@
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth, allowVerified, allowAdmin } from "./agent-auth.js";
+import { localInstanceId } from "./instance-identity.js";
 /**
  * Agent resource — serves as the Principal table in 1.0.
  *
@@ -40,6 +41,14 @@ export class Agent extends databases.flair.Agent {
         }
         content.createdAt = now;
         content.updatedAt = now;
+        // Write-time originatorInstanceId stamp (federation-edge-hardening slice
+        // 1) — see resources/Memory.ts's stampOriginatorInstanceId doc for the
+        // full contract. No-op if already set (never fires for a genuine local
+        // write; a federation-synced record never reaches this method — the
+        // merge path writes via the raw table object, bypassing this class).
+        if (content.originatorInstanceId == null) {
+            content.originatorInstanceId = await localInstanceId();
+        }
         return super.post(content, context);
     }
     async put(content) {
@@ -64,6 +73,11 @@ export class Agent extends databases.flair.Agent {
         // Protect immutable fields
         delete content.createdAt;
         delete content.publicKey; // key rotation goes through dedicated endpoint
+        // Write-time originatorInstanceId stamp — see post() above / Memory.ts's
+        // stampOriginatorInstanceId doc. No-op if already set.
+        if (content.originatorInstanceId == null) {
+            content.originatorInstanceId = await localInstanceId();
+        }
         return super.put(content);
     }
 }

package/dist/resources/AgentCard.js

@@ -29,7 +29,7 @@ export class AgentCard extends Resource {
         return {
             name: String(agent.name ?? agent.id ?? agentId),
             // Only an explicit kind="description" soul publishes — no private-soul
-            // fallback (ops-vz6j). See agentcard-fields.ts for the security rationale.
+            // fallback. See agentcard-fields.ts for the security rationale.
             description: selectPublicDescription(souls),
             url: String(agent.url ?? ""),
             version: String(agent.version ?? "1.0.0"),

package/dist/resources/AgentSeed.js

@@ -40,7 +40,7 @@ export class AgentSeed extends Resource {
     }
     async post(data) {
         // Harper v5 does not populate this.request on Resource subclasses —
-        // getContext() is the only reliable path (ops-sal4: the previous
+        // getContext() is the only reliable path (the previous
         // `(this as any).request` read was always undefined, so actorId was always
         // undefined and this belt-and-suspenders check fail-closed every request,
         // even from a real admin already verified by allowCreate()).