@tpsdev-ai/flair 0.21.0 → 0.22.1

package/dist/mcp-client-assertion.js

@@ -0,0 +1,364 @@
+/**
+ * RFC 7523 client_assertion signing — the Flair/consumer half of headless
+ * agent-auth to a Harper MCP `/mcp` endpoint.
+ *
+ * Builds + signs the `client_assertion` JWT a Flair agent presents to an
+ * OAuth token endpoint for the `client_credentials` grant with
+ * `private_key_jwt` client authentication (RFC 7523 §2.2), using the agent's
+ * EXISTING Ed25519 identity key — no new key material, no browser, no human.
+ *
+ * The exact claim shape here is deliberately pinned to what
+ * HarperFast/oauth PR #165 (`src/lib/mcp/clientAssertion.ts`,
+ * merged @ commit d48c3b2) verifies:
+ *   - header: `alg` exactly `EdDSA`; `typ` "JWT" when present.
+ *   - payload: `iss` = `sub` = `client_id`; `aud` = the token endpoint
+ *     (exact string match); `exp` required, ≤ 60s out; `iat` required;
+ *     `jti` required (replay guard, enforced server-side via
+ *     `assertionJtiStore.ts`).
+ * See test/unit/mcp-client-assertion.test.ts for a mirror of that
+ * verification, run against assertions this module produces.
+ *
+ * ── oauth#161/#162/#163, shipped in @harperfast/oauth@2.2.0 ─────────────────
+ * The token-endpoint grant that CONSUMES this assertion
+ * (`grant_type=client_credentials`) shipped as HarperFast/oauth PR #170
+ * (closes issues #161/#162) in the 2.2.0 release; rate limiting (#171,
+ * closes #163) shipped in the same release. Confirmed against the published
+ * package's source (`node_modules/@harperfast/oauth/dist/lib/mcp/token.js`,
+ * `.../cimd.js`), not guessed:
+ *   - `client_assertion_type` = `urn:ietf:params:oauth:client-assertion-
+ *     type:jwt-bearer`; `client_assertion` = the signed JWT; `client_id`
+ *     required in the form body and MUST equal the assertion's `iss`/`sub`
+ *     — already true here by construction (`buildTokenRequestForm`'s
+ *     `clientId` param is always the same value callers pass as
+ *     `signClientAssertion`'s `clientId`, which becomes both `iss` and
+ *     `sub`).
+ *   - RFC 8707 `resource` parameter: accepted, exact-match, fail-closed,
+ *     defaulting to the configured canonical resource — `buildTokenRequestForm`
+ *     already carries an optional `resource` pass-through (see below), and
+ *     `defaultMcpResource()` supplies the configured canonical default
+ *     (mirrors `resources/mcp-oauth-flag.ts`'s `mcpResource()` — the same
+ *     `<issuer>/mcp` value the AS will exact-match against).
+ *   - Issued token `sub` = `client_id`; access-token TTL default 300s
+ *     (`mcp.clientCredentials.accessTokenTtl`); no `refresh_token` — agents
+ *     re-mint on 401/near-expiry instead (see `getMcpAccessToken` below).
+ *   - Issuance is rate-limited per verified client_id
+ *     (`mcp.clientCredentials.rateLimit`, default 30/min) — debited AFTER
+ *     assertion verification, so a forged assertion can never drain a real
+ *     client's bucket. Over-limit is `429 {"error":"slow_down"}` with a
+ *     `Retry-After` header (seconds). `requestMcpAccessToken` below honors it.
+ * `requestMcpAccessToken` performs the real POST; `getMcpAccessToken` wraps
+ * it with the two consumer requirements the 2.2.0 rate limiter adds (pinned
+ * in flair#663's tracking-issue thread): token caching (reuse until
+ * near-expiry, mint sparingly) and jittered Retry-After backoff on 429.
+ * See docs/notes/mcp-agent-auth-consumer.md.
+ */
+import { createPrivateKey, createPublicKey, randomUUID, sign } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ─── RFC 7523 constants ─────────────────────────────────────────────────────
+/** RFC 7523 §2.2 value for `client_assertion_type`. */
+export const CLIENT_ASSERTION_TYPE_JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/**
+ * Maximum assertion lifetime (`exp - iat`), in seconds. Pinned to 60 to
+ * match HarperFast/oauth PR #165's `DEFAULT_MAX_EXPIRES_IN_SECONDS` — an
+ * assertion signed with a longer window would be rejected server-side.
+ */
+export const MAX_ASSERTION_LIFETIME_SECONDS = 60;
+// ─── Key loading ────────────────────────────────────────────────────────────
+/**
+ * Locate an agent's private key file. Search order mirrors `resolveKeyPath`
+ * in src/cli.ts (the existing TPS-Ed25519 REST-auth path) exactly, with one
+ * addition: an explicit `keysDirOverride` (this module's `--keys-dir` CLI
+ * flag) takes priority over everything, including `FLAIR_KEY_DIR`.
+ */
+export function resolveAgentKeyPath(agentId, keysDirOverride) {
+    const candidates = [
+        keysDirOverride ? join(keysDirOverride, `${agentId}.key`) : null,
+        process.env.FLAIR_KEY_DIR ? join(process.env.FLAIR_KEY_DIR, `${agentId}.key`) : null,
+        join(homedir(), ".flair", "keys", `${agentId}.key`),
+        join(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
+    ].filter((p) => Boolean(p));
+    return candidates.find((p) => existsSync(p)) ?? null;
+}
+/** Fixed ASN.1 prefix that turns a raw 32-byte Ed25519 seed into a PKCS8 DER key. */
+const ED25519_PKCS8_HEADER = Buffer.from("302e020100300506032b657004220420", "hex");
+/**
+ * Load an Ed25519 private key from disk. Accepts every format already in use
+ * across this repo's agent keys (mirrors `buildEd25519Auth` in src/cli.ts):
+ *   - raw 32-byte binary seed
+ *   - base64-encoded 32-byte seed
+ *   - base64-encoded full PKCS8 DER (the standard `~/.tps/secrets/flair/
+ *     <agentId>-priv.key` format written by flair-client.mjs et al.)
+ *   - raw PEM/DER bytes as a last-resort fallback
+ */
+export function loadEd25519PrivateKeyFromFile(filePath) {
+    const raw = readFileSync(filePath);
+    if (raw.length === 32) {
+        return createPrivateKey({
+            key: Buffer.concat([ED25519_PKCS8_HEADER, raw]),
+            format: "der",
+            type: "pkcs8",
+        });
+    }
+    const decoded = Buffer.from(raw.toString("utf-8").trim(), "base64");
+    if (decoded.length === 32) {
+        return createPrivateKey({
+            key: Buffer.concat([ED25519_PKCS8_HEADER, decoded]),
+            format: "der",
+            type: "pkcs8",
+        });
+    }
+    try {
+        return createPrivateKey({ key: decoded, format: "der", type: "pkcs8" });
+    }
+    catch {
+        return createPrivateKey(raw);
+    }
+}
+/** Derive the public JWK (OKP/Ed25519) for a loaded private key. */
+export function publicJwkFromPrivateKey(privateKey) {
+    const pub = createPublicKey(privateKey);
+    const jwk = pub.export({ format: "jwk" });
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || !jwk.x) {
+        throw new Error("private key is not an Ed25519 key");
+    }
+    return { kty: "OKP", crv: "Ed25519", x: jwk.x };
+}
+function clampExpiresIn(requested) {
+    const n = requested ?? MAX_ASSERTION_LIFETIME_SECONDS;
+    if (!Number.isFinite(n) || n <= 0)
+        return MAX_ASSERTION_LIFETIME_SECONDS;
+    return Math.min(n, MAX_ASSERTION_LIFETIME_SECONDS);
+}
+function base64urlJson(obj) {
+    return Buffer.from(JSON.stringify(obj), "utf8").toString("base64url");
+}
+/**
+ * Build + sign an RFC 7523 client_assertion JWT for the client_credentials
+ * grant. Pure given a KeyObject — callers load the key separately (see
+ * loadEd25519PrivateKeyFromFile) so this stays independently testable with
+ * an ephemeral test keypair.
+ */
+export function signClientAssertion(params) {
+    const { clientId, tokenEndpoint, privateKey } = params;
+    if (!clientId)
+        throw new Error("clientId is required");
+    if (!tokenEndpoint)
+        throw new Error("tokenEndpoint is required");
+    const expiresIn = clampExpiresIn(params.expiresInSeconds);
+    const iat = Math.floor(params.nowSeconds ?? Date.now() / 1000);
+    const exp = iat + expiresIn;
+    const jti = params.jti ?? randomUUID();
+    // header.typ is optional per RFC 7515 §4.1.9, but #165 accepts it when
+    // present (case-insensitively) — include it for maximum interop.
+    const header = { alg: "EdDSA", typ: "JWT" };
+    const claims = { iss: clientId, sub: clientId, aud: tokenEndpoint, exp, iat, jti };
+    const headerB64 = base64urlJson(header);
+    const payloadB64 = base64urlJson(claims);
+    const signingInput = `${headerB64}.${payloadB64}`;
+    // Ed25519 (EdDSA) takes no digest algorithm — pass null, per RFC 8032 and
+    // matching #165's own verify call (`verifySignature(null, ...)`).
+    const signature = sign(null, Buffer.from(signingInput), privateKey);
+    const assertion = `${signingInput}.${signature.toString("base64url")}`;
+    return { assertion, claims };
+}
+/**
+ * The form-body this assertion would be sent in, per oauth#162's scope (RFC
+ * 7523 `client_credentials` grant + RFC 8707 `resource`). Pure/testable;
+ * NOT sent anywhere by this module — see requestMcpAccessToken. Callers are
+ * responsible for passing the SAME `clientId` used to sign the assertion
+ * (`signClientAssertion`'s `iss`/`sub`) — every call site in this repo
+ * (`flair mcp token` in src/cli.ts) already does this from a single shared
+ * local.
+ */
+export function buildTokenRequestForm(params) {
+    const form = {
+        grant_type: "client_credentials",
+        client_assertion_type: CLIENT_ASSERTION_TYPE_JWT_BEARER,
+        client_assertion: params.assertion,
+        client_id: params.clientId,
+    };
+    if (params.resource)
+        form.resource = params.resource;
+    return form;
+}
+export class McpTokenRequestError extends Error {
+    status;
+    error;
+    constructor(message, status, error) {
+        super(message);
+        this.status = status;
+        this.error = error;
+        this.name = "McpTokenRequestError";
+    }
+}
+const DEFAULT_MAX_429_RETRIES = 3;
+// Ceiling on a single backoff sleep: a misconfigured or hostile server
+// returning an absurd Retry-After must not stall the caller indefinitely
+// (mirrors the plugin's own MAX_RETRY_AFTER_SECONDS defense-in-depth
+// posture at the source of the header, node_modules/@harperfast/oauth's
+// rateLimit.ts — this is the client-side counterpart of that cap).
+const MAX_BACKOFF_MS = 60_000;
+// Fallback backoff (exponential, doubling per attempt) when the server 429s
+// without a Retry-After header at all — should not happen against the
+// plugin (it always sets one, see mcp-client-assertion.ts's module header),
+// but a client MUST NOT hammer even a non-conformant server.
+const FALLBACK_BASE_MS = 1_000;
+/**
+ * POST the `client_credentials` grant to the MCP token endpoint (oauth#162,
+ * shipped in @harperfast/oauth@2.2.0's PR #170). On `429 slow_down`
+ * (issuance rate limit, #171/#163), honors the `Retry-After` header with
+ * FULL JITTER (sleep a random duration in `[0, Retry-After]`, per the
+ * standard token-bucket backoff pattern — never hammer, and never retry in
+ * lockstep with other rate-limited callers), retrying up to `maxRetries`
+ * times before giving up.
+ *
+ * Throws `McpTokenRequestError` on any non-2xx response (including the
+ * final 429). Never retries non-429 errors — those are the AS telling us
+ * the request itself is wrong (bad assertion, unresolvable client, wrong
+ * resource), and retrying identically would just repeat the same rejection
+ * (worse, it would burn a fresh `jti` for no reason on a client-side bug).
+ */
+export async function requestMcpAccessToken(form, tokenEndpoint, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const random = opts.random ?? Math.random;
+    const maxRetries = opts.maxRetries ?? DEFAULT_MAX_429_RETRIES;
+    const now = opts.now ?? Date.now;
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(form)) {
+        if (value !== undefined)
+            body.set(key, String(value));
+    }
+    for (let attempt = 0;; attempt++) {
+        const mintedAtMs = now();
+        const res = await fetchImpl(tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        if (res.status === 429 && attempt < maxRetries) {
+            // `res.headers.get()` returns null (not undefined) when absent, and
+            // `Number(null) === 0` — a bare `Number(...)` here would silently read
+            // a MISSING header as "retry immediately", not "no header present".
+            // Distinguish explicitly so absence falls through to the exponential
+            // fallback below instead.
+            const retryAfterHeader = res.headers.get("retry-after");
+            const retryAfterRaw = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
+            const baseMs = Number.isFinite(retryAfterRaw) && retryAfterRaw >= 0
+                ? retryAfterRaw * 1000
+                : FALLBACK_BASE_MS * 2 ** attempt;
+            const jitteredMs = Math.min(MAX_BACKOFF_MS, Math.round(random() * baseMs));
+            // Drain the body so the connection can be reused; the error payload
+            // isn't needed for a retry.
+            await res.body?.cancel?.().catch(() => { });
+            await sleep(jitteredMs);
+            continue;
+        }
+        let payload;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            throw new McpTokenRequestError(`MCP token endpoint returned a non-JSON response (HTTP ${res.status})`, res.status);
+        }
+        if (!res.ok) {
+            const errorCode = typeof payload?.error === "string" ? payload.error : "error";
+            const description = typeof payload?.error_description === "string" ? `: ${payload.error_description}` : "";
+            throw new McpTokenRequestError(`MCP token request failed (HTTP ${res.status} ${errorCode})${description}`, res.status, errorCode);
+        }
+        if (typeof payload?.access_token !== "string" || !payload.access_token) {
+            throw new McpTokenRequestError("MCP token endpoint response is missing access_token", res.status);
+        }
+        const expiresIn = Number.isFinite(payload.expires_in) ? Number(payload.expires_in) : 300;
+        return {
+            accessToken: payload.access_token,
+            tokenType: typeof payload.token_type === "string" ? payload.token_type : "Bearer",
+            expiresIn,
+            scope: typeof payload.scope === "string" ? payload.scope : undefined,
+            mintedAtMs,
+            expiresAtMs: mintedAtMs + expiresIn * 1000,
+        };
+    }
+}
+// ─── Token caching (consumer requirement — flair#663 tracking-issue thread) ─
+//
+// The 2.2.0 rate limiter (mcp.clientCredentials.rateLimit, default 30/min)
+// is debited PER MINT, not per use — so a caller that re-signs+re-requests
+// on every tool call would burn a real agent's quota for no reason. Cache
+// the minted token per (clientId, tokenEndpoint, resource) and reuse it
+// until it's within `refreshMarginMs` of expiry.
+const mcpTokenCache = new Map();
+function mcpTokenCacheKey(clientId, tokenEndpoint, resource) {
+    return `${clientId}${tokenEndpoint}${resource ?? ""}`;
+}
+/** Drop all cached tokens (tests only, or a caller that wants a hard reset — e.g. after rotating the agent's key). */
+export function clearMcpAccessTokenCache() {
+    mcpTokenCache.clear();
+}
+const DEFAULT_REFRESH_MARGIN_MS = 30_000;
+/**
+ * Mint sparingly: reuse a cached, not-near-expiry token for the same
+ * (clientId, tokenEndpoint, resource) rather than signing a fresh assertion
+ * and re-minting on every call. This is the mandatory consumer-side
+ * counterpart to the 2.2.0 rate limiter (pinned in flair#663's tracking
+ * comment: "mint sparingly and reuse until expiry... per-request minting
+ * would burn the bucket for no reason").
+ */
+export async function getMcpAccessToken(params) {
+    const now = (params.now ?? Date.now)();
+    const key = mcpTokenCacheKey(params.clientId, params.tokenEndpoint, params.resource);
+    const cached = mcpTokenCache.get(key);
+    const refreshMarginMs = params.refreshMarginMs ?? DEFAULT_REFRESH_MARGIN_MS;
+    if (!params.forceRefresh && cached && cached.expiresAtMs - now > refreshMarginMs) {
+        return cached;
+    }
+    const { assertion } = signClientAssertion({
+        clientId: params.clientId,
+        tokenEndpoint: params.tokenEndpoint,
+        privateKey: params.privateKey,
+        expiresInSeconds: params.expiresInSeconds,
+    });
+    const form = buildTokenRequestForm({ clientId: params.clientId, assertion, resource: params.resource });
+    const token = await requestMcpAccessToken(form, params.tokenEndpoint, {
+        fetchImpl: params.fetchImpl,
+        sleep: params.sleep,
+        random: params.random,
+        maxRetries: params.maxRetries,
+        now: params.now,
+    });
+    mcpTokenCache.set(key, token);
+    return token;
+}
+// ─── Convenience defaults (this Flair instance's own /mcp + oauth surface) ──
+//
+// Mirrors resources/mcp-oauth-flag.ts's mcpIssuer()/mcpResource() env-driven
+// defaults. Duplicated here (rather than imported) because src/ (this CLI's
+// build root, tsconfig.cli.json) and resources/ (tsconfig.json) are separate
+// TypeScript compilation roots with no existing cross-import in this repo —
+// keep both in sync if either changes. These are only DEFAULTS: every value
+// is overridable via CLI flags, since an agent may authenticate to a
+// DIFFERENT Harper MCP server than the one running this CLI (identity is
+// portable — the whole point of the design, see
+// ~/ops/FLAIR-AGENT-AUTH-CONSUMER-SPEC.md "Wiring / usage").
+/** `FLAIR_MCP_ISSUER`, falling back to `FLAIR_PUBLIC_URL`. */
+export function defaultMcpIssuer() {
+    const raw = (process.env.FLAIR_MCP_ISSUER ?? process.env.FLAIR_PUBLIC_URL ?? "").trim();
+    return raw || undefined;
+}
+/** `${issuer}/mcp` — the RFC 8707 resource this instance's /mcp binds to. */
+export function defaultMcpResource() {
+    const iss = defaultMcpIssuer();
+    return iss ? `${iss.replace(/\/+$/, "")}/mcp` : undefined;
+}
+/** `${issuer}/oauth/mcp/token` — matches HarperFast/oauth's wellKnown.ts discovery doc. */
+export function defaultMcpTokenEndpoint() {
+    const iss = defaultMcpIssuer();
+    return iss ? `${iss.replace(/\/+$/, "")}/oauth/mcp/token` : undefined;
+}
+/** `${issuer}/MCPClientMetadata/{agentId}` — matches resources/MCPClientMetadata.ts. */
+export function defaultMcpClientId(agentId) {
+    const iss = defaultMcpIssuer();
+    return iss ? `${iss.replace(/\/+$/, "")}/MCPClientMetadata/${agentId}` : undefined;
+}

package/dist/probe.js

@@ -0,0 +1,97 @@
+/**
+ * probe.ts — post-restart instance verification.
+ *
+ * Shared by `flair upgrade`'s local post-restart verification (flair#635)
+ * and the planned Fabric fleet verify sweep (flair#636, peer-at-a-time
+ * rolling restart gate). `probeInstance()` answers three questions about a
+ * running Flair instance:
+ *
+ *   1. Is it reachable at all? (GET /Health — public, no auth, polled until
+ *      it answers or the time budget runs out.)
+ *   2. Does an authenticated request round-trip successfully? Credential
+ *      resolution is ENTIRELY the caller's responsibility via the injected
+ *      `authedGet` — probeInstance never resolves credentials itself. Local
+ *      `flair upgrade` dogfoods `api()`'s local-credential resolution
+ *      (flair#640: FLAIR_TOKEN > FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD env >
+ *      agent Ed25519 key > ~/.flair/admin-pass file); a future Fabric fleet
+ *      check will instead build Fabric admin Basic auth per peer. Same
+ *      shape, different credentials — that's the reuse.
+ *   3. Does the reported running version match what was just installed?
+ *      Read from the authenticated GET /HealthDetail response's `version`
+ *      field (resources/health.ts resolves it from the RUNNING process's
+ *      own package.json — it only changes once the process actually
+ *      restarts onto new code, so it can't be spoofed by a package.json
+ *      that changed on disk but hasn't been loaded yet).
+ *
+ * Never throws — every failure mode is expressed structurally in
+ * ProbeResult so callers can render (or automate a rollback decision from)
+ * a clear reason instead of catching an exception.
+ */
+export const DEFAULT_PROBE_TIMEOUT_MS = 60_000;
+export const DEFAULT_PROBE_POLL_INTERVAL_MS = 500;
+export const DEFAULT_PROBE_VERSION_PATH = "/HealthDetail";
+/**
+ * Poll `${baseUrl}/Health` until it answers 2xx or `timeoutMs` elapses, then
+ * (if `authedGet` is given) make ONE authenticated GET against
+ * `versionPath` to confirm auth works and read the running version.
+ */
+export async function probeInstance(baseUrl, opts = {}) {
+    const { expectVersion, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS, pollIntervalMs = DEFAULT_PROBE_POLL_INTERVAL_MS, fetchImpl = fetch, authedGet, versionPath = DEFAULT_PROBE_VERSION_PATH, } = opts;
+    const base = baseUrl.replace(/\/+$/, "");
+    const deadline = Date.now() + timeoutMs;
+    let healthy = false;
+    let lastHealthError;
+    for (;;) {
+        try {
+            const res = await fetchImpl(`${base}/Health`, { signal: AbortSignal.timeout(Math.min(5000, timeoutMs)) });
+            if (res.ok) {
+                healthy = true;
+                break;
+            }
+            lastHealthError = `HTTP ${res.status}`;
+        }
+        catch (err) {
+            lastHealthError = err?.message ?? String(err);
+        }
+        if (Date.now() >= deadline)
+            break;
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    if (!healthy) {
+        return {
+            healthy: false,
+            authenticated: null,
+            version: null,
+            versionMatch: null,
+            ok: false,
+            error: `instance did not answer ${base}/Health within ${timeoutMs}ms` +
+                (lastHealthError ? ` (last error: ${lastHealthError})` : ""),
+        };
+    }
+    if (!authedGet) {
+        return { healthy: true, authenticated: null, version: null, versionMatch: null, ok: true };
+    }
+    let version = null;
+    let authError;
+    try {
+        const body = await authedGet(versionPath);
+        version = typeof body?.version === "string" ? body.version : null;
+    }
+    catch (err) {
+        authError = err?.message ?? String(err);
+    }
+    const authenticated = authError === undefined;
+    let versionMatch = null;
+    if (authenticated && expectVersion !== undefined) {
+        versionMatch = version === expectVersion;
+    }
+    const ok = healthy && authenticated && versionMatch !== false;
+    let error;
+    if (!authenticated) {
+        error = `authenticated request to ${base}${versionPath} failed: ${authError}`;
+    }
+    else if (versionMatch === false) {
+        error = `version mismatch: expected ${expectVersion}, instance reports ${version ?? "unknown"}`;
+    }
+    return { healthy, authenticated, version, versionMatch, ok, error };
+}

package/dist/rem/runner.js

@@ -5,22 +5,32 @@
  *   1. Pre-flight: check pause sentinel / FLAIR_REM_PAUSE env. Exit clean if paused.
  *   2. Snapshot agent state (memory + soul) to ~/.flair/snapshots/<agent>/.
  *   3. Maintenance — delegate to /MemoryMaintenance (same code path `flair rem light` uses).
- *   4. (slice-2 next) trust-tier filter on input memories.
- *   5. (slice-2 next) distillation — call /ReflectMemories, persist candidates.
+ *   4. Trust-tier filter on input memories — permanently deferred (see below).
+ *   5. Distillation — call /ReflectMemories with execute:true, persist staged
+ *      candidate ids to the audit row.
  *   6. Append a row to ~/.flair/logs/rem-nightly.jsonl.
  *
  * Status today:
- *   - Steps 1, 2, 6 shipped in slice-1 PR-1 (#414).
- *   - Step 3 (maintenance) ships in this PR — fills `archived`/`expired` in
- *     the audit row.
- *   - Steps 4, 5 are slice-2 follow-ups; require an in-process distillation
- *     LLM path (today `/ReflectMemories` returns a prompt for human/agent
- *     consumption, not server-side candidate generation).
+ *   - Steps 1, 2 shipped in slice-1 PR-1 (#414).
+ *   - Step 3 (maintenance) shipped in a prior slice-2 PR — fills
+ *     `archived`/`expired` in the audit row.
+ *   - Step 4: per specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3B,
+ *     "Deferred from parent § 4 step 4" — trust tiers aren't derivable yet
+ *     (that's the emergent-trust arc). The input filter stays as today (own
+ *     agent, non-archived, non-permanent, scope window); the safety net for
+ *     un-tiered input is structural — candidates are staged, never
+ *     auto-promoted.
+ *   - Step 5 (distillation) ships in this PR: calls `/ReflectMemories` with
+ *     `execute: true` after maintenance succeeds. `dryRun` skips the call
+ *     entirely (staging rows + spending model tokens are side effects).
+ *   - Step 6 shipped in slice-1 PR-1.
  *
  * The audit row's `slice` field tells readers which steps populated which
  * counts: `slice: "1"` rows have `archived`/`expired` undefined; `slice:
- * "2-maintenance"` rows populate them; future slice-2 rows will populate
- * `consolidated` and `candidates`.
+ * "2-maintenance"` rows populate them but distillation didn't run this cycle
+ * (dry-run skip); `slice: "2"` rows had distillation attempted — check
+ * `candidates` for staged ids on success, `errors` for a `distillation:`
+ * entry on failure (maintenance results still stand either way).
  *
  * Pure dependency injection so the runner is unit-testable without Harper.
  * The CLI wires the real `apiCall` + `pkgVersion`; tests pass stubs.
@@ -64,6 +74,29 @@ function asArray(raw) {
     }
     return [];
 }
+/**
+ * Best-effort extraction of a readable message out of a thrown API error.
+ * `apiCall` implementations (see `api()` in src/cli.ts) throw
+ * `Error(responseBodyText)` for non-2xx HTTP responses — /ReflectMemories's
+ * 503 (no backend configured) and 502 (distillation_failed) bodies are JSON
+ * `{ error: string, detail?: string }`. Unwraps that shape into a single
+ * string so distinct failure modes read distinctly in the audit log instead
+ * of as a raw JSON blob; falls back to the raw input for network errors or
+ * any other shape.
+ */
+function describeApiError(err) {
+    const message = typeof err === "string" ? err : err?.message ?? String(err);
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed && typeof parsed === "object" && typeof parsed.error === "string") {
+            return parsed.detail ? `${parsed.error}: ${parsed.detail}` : parsed.error;
+        }
+    }
+    catch {
+        // Not a JSON error body — network error, plain string, etc.
+    }
+    return message;
+}
 /**
  * Counts pending memory candidates for the agent.
  *
@@ -199,6 +232,42 @@ export async function runNightlyCycle(opts) {
         appendLogRow(logPath, row);
         return { status: "failed", logRow: row, snapshotPath };
     }
+    // Step 5: distillation — call /ReflectMemories with execute:true, now that
+    // maintenance has succeeded. Per spec § 3B, dryRun skips the call entirely:
+    // staging MemoryCandidate rows and spending model tokens are side effects,
+    // the same way dryRun skips the snapshot write.
+    // When the call IS attempted (success or failure), the audit row's `slice`
+    // flips to "2" — "2-maintenance" is reserved for the dry-run skip case.
+    let candidates;
+    if (!opts.dryRun) {
+        sliceLabel = "2";
+        try {
+            const reflectRaw = await opts.apiCall("POST", "/ReflectMemories", {
+                agentId: opts.agentId,
+                execute: true,
+            });
+            const obj = (reflectRaw && typeof reflectRaw === "object") ? reflectRaw : {};
+            if (obj.error) {
+                // Defensive: a 200 response shouldn't carry { error }, since
+                // MemoryReflect signals failure via HTTP status (503/502) — apiCall
+                // implementations throw for those. Handled the same way regardless.
+                errors.push(`distillation: ${describeApiError(obj.error)}`);
+            }
+            else {
+                const staged = asArray(obj.candidates);
+                candidates = staged
+                    .map((c) => (c && typeof c === "object" ? c.id : c))
+                    .filter((id) => typeof id === "string");
+            }
+        }
+        catch (err) {
+            // Distillation failure is recorded, not fatal — maintenance already
+            // succeeded and the cycle's guaranteed steps are done (spec § 3B item
+            // 3). Zero partial candidates is guaranteed server-side (all-or-
+            // nothing staging in /ReflectMemories).
+            errors.push(`distillation: ${describeApiError(err?.message ?? err)}`);
+        }
+    }
     // Step 6: log
     const row = {
         ...baseRow,
@@ -211,10 +280,11 @@ export async function runNightlyCycle(opts) {
         pendingCandidates,
         archived,
         expired,
+        candidates,
         durationMs: Date.now() - startedMs,
         errors,
-        // `consolidated` and `candidates` populate when slice-2 PR-4 (distillation)
-        // lands; today they remain undefined so the row is honest about what ran.
+        // `consolidated` remains undefined — this runner has no consolidation
+        // step; it's reserved for a future slice that adds one.
     };
     appendLogRow(logPath, row);
     return { status: row.status, logRow: row, snapshotPath };