brainclaw 1.14.0 → 1.16.0

package/dist/core/execution.js

@@ -143,17 +143,37 @@ export async function attemptExecution(invoke, options) {
     const adapter = options.adapter ?? defaultExecutionAdapter;
     // No invoke command available (IDE-only agents, etc.)
     if (!invoke) {
-        return { execution_status: 'inbox_only' };
+        return { execution_status: 'inbox_only', execution_reason: 'no_invoke_command' };
     }
     const spawnCheck = adapter.canSpawn(options.agent);
-    // Opt-out or can't spawn: return command for manual execution
-    // Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes correctly
-    if (!options.autoExecute || !spawnCheck.canSpawn) {
+    // pln#626 Phase 1 — split the old `(!autoExecute || !spawnCheck.canSpawn)`
+    // branch, which collapsed two very different outcomes into one silent
+    // command_ready_manual (no reason, no failure_kind — it even discarded
+    // spawnCheck.reason). Callers could not tell "you didn't ask me to spawn"
+    // apart from "I tried and can't".
+    // (1) autoExecute explicitly disabled: a deliberate manual handoff, NOT a
+    // failure. Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes.
+    if (!options.autoExecute) {
         const manual = adapter.prepareManualCommand(invoke, options);
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
             shell: manual.shell,
+            execution_reason: 'auto_execute_disabled',
+        };
+    }
+    // (2) autoExecute requested but the agent cannot be spawned here: this IS a
+    // failure of the caller's intent. Surface spawnCheck.reason (previously
+    // dropped) instead of returning a bare manual command.
+    if (!spawnCheck.canSpawn) {
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+            error: spawnCheck.reason,
+            failure_kind: 'not_spawnable',
+            execution_reason: 'not_spawnable',
         };
     }
     // pln#531 — isolation invariant: a spawned worker MUST run in its own
@@ -179,6 +199,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: 'Refusing to spawn without an isolated worktree: with no worktree the worker would run in the integration repo and edit the main tree. Fix worktree creation (see claim worktreeWarning) or run the command manually inside a worktree.',
             failure_kind: 'spawn_no_worktree',
+            execution_reason: 'spawn_no_worktree',
         };
     }
     // Capacity guard: skip if agent is at max concurrent tasks
@@ -201,6 +222,7 @@ export async function attemptExecution(invoke, options) {
                 shell: manual.shell,
                 error: `Spawn skipped: ${instanceCheck.reason}. Use the command manually.`,
                 failure_kind: 'spawn_capacity',
+                execution_reason: 'spawn_capacity',
             };
         }
     }
@@ -239,6 +261,7 @@ export async function attemptExecution(invoke, options) {
                     shell: manual.shell,
                     error: `Spawn launched (pid ${result.pid}) but assignment ${options.assignmentId} did not acknowledge within ${handshakeTimeoutMs}ms`,
                     failure_kind: 'spawn_no_handshake',
+                    execution_reason: 'spawn_no_handshake',
                     pid: result.pid,
                 };
             }
@@ -280,6 +303,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: `Spawn failed (${errorMsg}), falling back to manual execution`,
             failure_kind: 'spawn_failed',
+            execution_reason: 'spawn_failed',
         };
     }
 }

package/dist/core/facade-schema.js

@@ -1,10 +1,17 @@
 import { z } from 'zod';
 export const ExecutionStatusSchema = z.enum(['delivered_and_started', 'command_ready_manual', 'inbox_only']);
 export const WorkIntentSchema = z.enum(['execute', 'consult', 'resume', 'review']);
-// pln#492 phase 2.c — 'ideate' opens an ideation loop with a proposal seed
-// artifact. The handler does NOT yet dispatch turns (driver wire-up is
-// phase 2.d). Callers receive loop_id and may drive the loop manually via
-// bclaw_loop intent='turn' / 'advance' until the dispatch path lands.
+// pln#626 — coordinate intents split into three honest contracts:
+//  • SPAWNING (assign / review / reroute, + multi-agent ideate): create a claim
+//    + worktree and, when autoExecute is on, spawn a worker on the brief.
+//    'ideate' with targetAgents advances to critique and spawns one
+//    worktree-isolated critic worker per target (Phase 2, Option B); single-
+//    agent ideate just opens the loop for the champion to drive manually via
+//    bclaw_loop intent='turn'/'advance'.
+//  • INBOX-ONLY (consult): delivers the brief to the target inbox; autoExecute
+//    is a no-op here (never silently ignored).
+//  • READ-ONLY (summarize): reads a thread and returns a summary — no claim,
+//    no dispatch, no execution_status; autoExecute is irrelevant.
 export const CoordinateIntentSchema = z.enum(['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate']);
 export const WorkRequestSchema = z.object({
     intent: WorkIntentSchema,
@@ -109,6 +116,18 @@ export const CoordinateRequestSchema = z.object({
      * rejected as `preset_kind_mismatch`.
      */
     preset: z.string().min(1).optional(),
+    /**
+     * pln#520 step 3 / pln#606 — model to run on the spawned worker, decoupled
+     * from agent identity. Passed through to `resolveModel({ override })` and
+     * injected as `<model_flag> <model>` into the invoke command for agents that
+     * declare a `model_flag` (e.g. `claude-code --model sonnet`, `codex exec
+     * --model …`, `copilot --model …`). No-op for agents whose template already
+     * pins a model (e.g. the `claude-sonnet` pseudo-identity) or that declare no
+     * `model_flag`. Highest-priority link in the model resolution chain. Ignored
+     * by intents that don't spawn a worker (summarize). Mirrors the CLI
+     * `brainclaw dispatch run --model <name>` flag for CLI/MCP parity.
+     */
+    model: z.string().min(1).optional(),
 });
 export const FacadeArtifactSchema = z.object({
     type: z.string(),
@@ -160,6 +179,13 @@ export const FacadeResponseSchema = z.object({
     session_id: z.string().optional(),
     warnings: z.array(z.string()),
     execution_status: ExecutionStatusSchema.optional(),
+    /**
+     * pln#626 Phase 1 — machine-readable reason accompanying execution_status
+     * when it is not `delivered_and_started`: auto_execute_disabled (manual
+     * handoff), not_spawnable, spawn_no_worktree/capacity/no_handshake/failed,
+     * or intent_inbox_only (consult/ideate). Absent when everything spawned.
+     */
+    execution_reason: z.string().optional(),
     /** pln#503 phase 3.3: present when execution_status === 'delivered_and_started'. */
     verify_with: VerifyWithSchema.optional(),
     /**

package/dist/core/federation-cloud.js

@@ -1,18 +1,31 @@
 import { loadConfig } from './config.js';
 import { logger } from './logger.js';
+import { buildCloudWriteHeaders, resolveCloudSigningIdentity, } from './federation-signing.js';
 const DEFAULT_API_URL = 'https://app.brainclaw.dev';
+function envFlag(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
 function resolveCloudConfig(cwd) {
     const envApiUrl = process.env.BRAINCLAW_CLOUD_URL;
     const envApiKey = process.env.BRAINCLAW_CLOUD_API_KEY;
+    const envProjectId = process.env.BRAINCLAW_PROJECT_ID;
+    const envRequireSigned = process.env.BRAINCLAW_CLOUD_REQUIRE_SIGNED;
     let configEnabled = false;
     let configEndpoint;
     let configApiKey;
+    let configProjectId;
+    let configRequireSigned = false;
     try {
         const config = loadConfig(cwd);
         if (config.cloud_sync) {
             configEnabled = config.cloud_sync.enabled === true;
             configEndpoint = config.cloud_sync.endpoint;
             configApiKey = config.cloud_sync.api_key;
+            configProjectId = config.cloud_sync.project_id;
+            configRequireSigned = config.cloud_sync.require_signed === true;
         }
     }
     catch {
@@ -24,7 +37,22 @@ function resolveCloudConfig(cwd) {
     // Env-supplied key implies explicit opt-in; config flag is the alternative
     const enabled = Boolean(envApiKey) || configEnabled;
     const apiUrl = envApiUrl ?? configEndpoint ?? DEFAULT_API_URL;
-    return { apiUrl, apiKey, enabled };
+    const projectId = envProjectId?.trim() || configProjectId;
+    const requireSigned = envRequireSigned !== undefined ? envFlag(envRequireSigned) : configRequireSigned;
+    return { apiUrl, apiKey, enabled, projectId, requireSigned };
+}
+/**
+ * Build the outgoing headers for a runtime write, signing when possible.
+ * Returns undefined when `require_signed` is set but no signing identity is
+ * available — the caller must NOT send the request (fail-closed).
+ */
+function writeHeaders(body, cloud, cwd) {
+    const signing = resolveCloudSigningIdentity(cwd);
+    return buildCloudWriteHeaders(body, {
+        apiKey: cloud.apiKey,
+        signing,
+        requireSigned: cloud.requireSigned,
+    });
 }
 export async function pushSignalToCloud(message, cwd) {
     const cloud = resolveCloudConfig(cwd);
@@ -32,14 +60,17 @@ export async function pushSignalToCloud(message, cwd) {
         logger.debug('Cloud not configured — skipping push');
         return false;
     }
+    const body = JSON.stringify(message);
+    const headers = writeHeaders(body, cloud, cwd);
+    if (!headers) {
+        logger.warn('Cloud push refused: require_signed is set but no approved signing identity/key is available (fail-closed).');
+        return false;
+    }
     try {
         const response = await fetch(`${cloud.apiUrl}/api/v1/messages`, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'X-API-Key': cloud.apiKey,
-            },
-            body: JSON.stringify(message),
+            headers,
+            body,
         });
         if (!response.ok) {
             logger.debug(`Cloud push failed: ${response.status} ${response.statusText}`);
@@ -83,14 +114,17 @@ export async function pushBoardToCloud(projectName, boardData, cwd) {
     const cloud = resolveCloudConfig(cwd);
     if (!cloud)
         return false;
+    const body = JSON.stringify(boardData);
+    const headers = writeHeaders(body, cloud, cwd);
+    if (!headers) {
+        logger.warn('Cloud board push refused: require_signed is set but no approved signing identity/key is available (fail-closed).');
+        return false;
+    }
     try {
         const response = await fetch(`${cloud.apiUrl}/api/v1/board/${encodeURIComponent(projectName)}`, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'X-API-Key': cloud.apiKey,
-            },
-            body: JSON.stringify(boardData),
+            headers,
+            body,
         });
         return response.ok;
     }
@@ -98,6 +132,35 @@ export async function pushBoardToCloud(projectName, boardData, cwd) {
         return false;
     }
 }
+export async function pushClaimToCloud(payload, cwd) {
+    const cloud = resolveCloudConfig(cwd);
+    if (!cloud)
+        return { kind: 'not_configured' };
+    const body = JSON.stringify(payload);
+    const headers = writeHeaders(body, cloud, cwd);
+    if (!headers)
+        return { kind: 'fail_closed' };
+    try {
+        const response = await fetch(`${cloud.apiUrl}/api/v1/claims/${encodeURIComponent(payload.id)}`, {
+            method: 'PUT',
+            headers,
+            body,
+        });
+        let code = null;
+        try {
+            const data = (await response.json());
+            const raw = data.code ?? data.status;
+            code = typeof raw === 'string' ? raw : null;
+        }
+        catch {
+            // Non-JSON body — leave code null; the HTTP status still classifies it.
+        }
+        return { kind: 'response', httpStatus: response.status, code };
+    }
+    catch (err) {
+        return { kind: 'network_error', error: err.message };
+    }
+}
 export function isCloudConfigured(cwd) {
     return resolveCloudConfig(cwd) !== undefined;
 }
@@ -111,4 +174,72 @@ export function isCloudSyncEnabled(cwd) {
     const cloud = resolveCloudConfig(cwd);
     return cloud !== undefined && cloud.enabled;
 }
+/**
+ * Startup diagnostics for the cloud bridge: remote health, resolved signing
+ * identity, approved-agent lookup, and a local↔remote key fingerprint match.
+ * Never throws — every probe degrades to an error field so the CLI can print a
+ * complete report.
+ */
+export async function diagnoseCloudBridge(cwd) {
+    const cloud = resolveCloudConfig(cwd);
+    const apiUrl = cloud?.apiUrl ?? process.env.BRAINCLAW_CLOUD_URL ?? DEFAULT_API_URL;
+    const signingIdentity = resolveCloudSigningIdentity(cwd);
+    const diag = {
+        configured: Boolean(cloud),
+        enabled: cloud?.enabled ?? false,
+        apiUrl,
+        projectId: cloud?.projectId,
+        requireSigned: cloud?.requireSigned ?? false,
+        signing: signingIdentity
+            ? {
+                available: true,
+                cloudAgentId: signingIdentity.cloudAgentId,
+                agentName: signingIdentity.agentName,
+                fingerprint: signingIdentity.fingerprint,
+            }
+            : {
+                available: false,
+                reason: 'No approved agent id/name configured, or the agent has no local Ed25519 key. '
+                    + 'Register the agent and its key with the cloud first.',
+            },
+    };
+    if (!cloud)
+        return diag;
+    // Remote health
+    try {
+        const res = await fetch(`${apiUrl}/api/v1/health`);
+        const data = (await res.json());
+        diag.health = { ok: res.ok, status: String(data.status ?? ''), version: String(data.version ?? '') };
+    }
+    catch (e) {
+        diag.health = { ok: false, error: e.message };
+    }
+    // Approved-agent lookup + fingerprint match
+    if (signingIdentity) {
+        try {
+            const res = await fetch(`${apiUrl}/api/v1/agents/${encodeURIComponent(signingIdentity.cloudAgentId)}`, {
+                headers: { 'X-API-Key': cloud.apiKey },
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                const agent = data.agent;
+                diag.approvedAgent = {
+                    found: Boolean(agent),
+                    status: agent?.status,
+                    trustLevel: agent?.trust_level,
+                    fingerprintMatch: agent?.key_fingerprint
+                        ? agent.key_fingerprint === signingIdentity.fingerprint
+                        : false,
+                };
+            }
+            else {
+                diag.approvedAgent = { found: false, error: `HTTP ${res.status}` };
+            }
+        }
+        catch (e) {
+            diag.approvedAgent = { found: false, error: e.message };
+        }
+    }
+    return diag;
+}
 //# sourceMappingURL=federation-cloud.js.map

package/dist/core/federation-outbox.js

@@ -0,0 +1,292 @@
+/**
+ * Federation outbox — durable queue for signed edge → cloud runtime writes
+ * (pln#101 Phase 2, increment 1: CLAIM). Design of record: decision dec#123.
+ *
+ * Layout under `.brainclaw/coordination/federation/`:
+ *   outbox/<id>@r<rev>.json   — pending, awaiting push
+ *   sent/<id>@r<rev>.json     — archived after a successful/superseded push (the marker)
+ *   parked/<id>@r<rev>.json   — dead-letter (conflict / persistent 4xx)
+ *
+ * Enqueue is DIFF-BASED at the claim persistence chokepoint (saveClaimUnlocked),
+ * which runs under the store mutation mutex, so per-claim rev reservation is
+ * serialized for free (no separate lock). Only lifecycle transitions enqueue;
+ * mid-life saves (same status) and cloud-origin materialization (suppressEnqueue)
+ * do not. All work here is local file I/O — never network.
+ *
+ * @module
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { nowISO } from './ids.js';
+import { resolveEntityDir } from './io.js';
+import { isCloudSyncEnabled } from './federation-cloud.js';
+import { logger } from './logger.js';
+// ── Directories ─────────────────────────────────────────────────────────────
+function federationSubdir(sub, cwd, mode) {
+    return resolveEntityDir(`federation/${sub}`, cwd ?? process.cwd(), mode);
+}
+function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+// ── Canonical content hash (edge is the sole computer; cloud stores+compares) ──
+/** Deterministic JSON with recursively sorted object keys. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/**
+ * Canonical content hash of a claim's SEMANTIC body — excludes the rev, all
+ * volatile/local-only fields (user, model, adopted_at, enqueue metadata), and
+ * the signature timestamp. Same-rev + different hash ⇒ genuinely divergent
+ * bodies (a conflict the cloud must not silently absorb).
+ */
+export function claimContentHash(claim) {
+    // Identity fields (agent_id/agent_name) are excluded: they are constant over a
+    // claim's life and the local↔cloud agent-id mapping is a transport concern,
+    // not claim content. What matters for divergence detection is the lifecycle body.
+    const body = {
+        id: claim.id,
+        status: claim.status,
+        scope: claim.scope,
+        description: claim.description,
+        plan_id: claim.plan_id ?? null,
+        host_id: claim.host_id ?? null,
+        session_id: claim.session_id ?? null,
+        expires_at: claim.expires_at ?? null,
+        worktree_path: claim.worktree_path ?? null,
+        created_at: claim.created_at,
+        released_at: claim.released_at ?? null,
+    };
+    return crypto.createHash('sha256').update(stableStringify(body)).digest('hex');
+}
+function buildClaimPayload(claim, rev, contentHash) {
+    return {
+        id: claim.id,
+        rev,
+        agent_name: claim.agent,
+        scope: claim.scope,
+        description: claim.description,
+        status: claim.status,
+        plan_id: claim.plan_id ?? null,
+        host_id: claim.host_id ?? null,
+        session_id: claim.session_id ?? null,
+        expires_at: claim.expires_at ?? null,
+        worktree_path: claim.worktree_path ?? null,
+        created_at: claim.created_at,
+        released_at: claim.released_at ?? null,
+        content_hash: contentHash,
+    };
+}
+// ── Rev reservation (serialized by the caller's store mutex) ───────────────────
+const REV_RE = /@r(\d+)\.json$/;
+function revsForId(id, dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const revs = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.startsWith(`${id}@r`))
+            continue;
+        const m = name.match(REV_RE);
+        if (m)
+            revs.push(parseInt(m[1], 10));
+    }
+    return revs;
+}
+/** Highest rev already reserved for this id across outbox + sent (0 if none). */
+function maxRevForId(id, cwd) {
+    const all = [
+        ...revsForId(id, federationSubdir('outbox', cwd, 'read')),
+        ...revsForId(id, federationSubdir('sent', cwd, 'read')),
+    ];
+    return all.length ? Math.max(...all) : 0;
+}
+function recordFilename(id, rev) {
+    return `${id}@r${rev}.json`;
+}
+function writeRecordAtomic(dir, filename, record) {
+    ensureDir(dir);
+    const finalPath = path.join(dir, filename);
+    const tmpPath = path.join(dir, `.${filename}.${process.pid}.tmp`);
+    fs.writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`, 'utf-8');
+    fs.renameSync(tmpPath, finalPath);
+}
+// ── Enablement gate (memoized per cwd — resolve config once per process) ───────
+const enabledCache = new Map();
+function syncEnabledCached(cwd) {
+    const key = cwd ?? process.cwd();
+    const cached = enabledCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    let value = false;
+    try {
+        value = isCloudSyncEnabled(cwd);
+    }
+    catch {
+        // Missing/unreadable config → treat federation as disabled.
+    }
+    enabledCache.set(key, value);
+    return value;
+}
+/** Test/hook seam: drop the memoized enablement (config changed on disk). */
+export function clearFederationEnablementCache() {
+    enabledCache.clear();
+}
+/**
+ * Cheap gate for the persistence seam: is a federation enqueue possibly needed?
+ * Lets the caller skip the prev-status load entirely when not federating.
+ */
+export function isFederationEnqueueActive(cwd, suppress) {
+    return !suppress && syncEnabledCached(cwd);
+}
+// ── Enqueue (the diff-based seam entry point) ──────────────────────────────────
+/**
+ * Enqueue a claim lifecycle transition for cloud sync, if it qualifies.
+ *
+ * Called from saveClaimUnlocked (under the store mutation mutex). Enqueues iff:
+ * cloud sync is enabled, not suppressed (cloud-origin materialization), and the
+ * save is a real transition — a create, or a status change. Mid-life saves that
+ * do not change status do NOT enqueue (dec#123). Never throws to the caller.
+ *
+ * Returns the reserved rev, or null when nothing was enqueued.
+ */
+export function maybeEnqueueClaimTransition(claim, prevStatus, created, cwd, suppress) {
+    try {
+        if (suppress)
+            return null;
+        if (!syncEnabledCached(cwd))
+            return null;
+        const isTransition = created || prevStatus !== claim.status;
+        if (!isTransition)
+            return null;
+        const rev = maxRevForId(claim.id, cwd) + 1;
+        const contentHash = claimContentHash(claim);
+        const record = {
+            op: 'upsert_claim',
+            entity_type: 'claim',
+            entity_id: claim.id,
+            rev,
+            from_status: prevStatus ?? null,
+            to_status: claim.status,
+            content_hash: contentHash,
+            payload: buildClaimPayload(claim, rev, contentHash),
+            enqueued_at: nowISO(),
+            attempts: 0,
+            last_status: null,
+            last_error: null,
+            last_attempt_at: null,
+        };
+        writeRecordAtomic(federationSubdir('outbox', cwd, 'write'), recordFilename(claim.id, rev), record);
+        logger.debug(`Federation outbox: enqueued claim ${claim.id}@r${rev} (${prevStatus ?? 'new'}→${claim.status})`);
+        return rev;
+    }
+    catch (err) {
+        // Federation bookkeeping must never break a claim write.
+        logger.debug('Federation outbox enqueue failed (non-fatal):', err);
+        return null;
+    }
+}
+// ── Drain-side helpers (used by `brainclaw federation sync`) ───────────────────
+function loadRecordsFrom(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.json') || name.startsWith('.'))
+            continue;
+        const filepath = path.join(dir, name);
+        try {
+            out.push({ record: JSON.parse(fs.readFileSync(filepath, 'utf-8')), filepath });
+        }
+        catch (err) {
+            logger.debug(`Federation outbox: skipping unreadable record ${name}:`, err);
+        }
+    }
+    return out;
+}
+export function listOutboxRecords(cwd) {
+    return loadRecordsFrom(federationSubdir('outbox', cwd, 'read'))
+        .sort((a, b) => (a.record.entity_id.localeCompare(b.record.entity_id)) || (a.record.rev - b.record.rev));
+}
+/** Highest rev already archived in sent/ for an id (the sync marker). 0 if none. */
+export function sentMarkerRev(id, cwd) {
+    const revs = revsForId(id, federationSubdir('sent', cwd, 'read'));
+    return revs.length ? Math.max(...revs) : 0;
+}
+function removeFileIfExists(filepath) {
+    try {
+        if (fs.existsSync(filepath))
+            fs.unlinkSync(filepath);
+    }
+    catch { /* best-effort */ }
+}
+/** Archive a record from outbox → sent (success or superseded). */
+export function archiveToSent(rec, meta, cwd) {
+    const sentDir = federationSubdir('sent', cwd, 'write');
+    const archived = {
+        ...rec.record,
+        synced_at: nowISO(),
+        http_status: meta.http_status,
+    };
+    writeRecordAtomic(sentDir, recordFilename(rec.record.entity_id, rec.record.rev), archived);
+    removeFileIfExists(rec.filepath);
+}
+/** Move a record from outbox → parked (dead-letter). */
+export function parkRecord(rec, reason, cwd) {
+    const parkedDir = federationSubdir('parked', cwd, 'write');
+    const parked = {
+        ...rec.record,
+        parked_at: nowISO(),
+        parked_reason: reason,
+    };
+    writeRecordAtomic(parkedDir, recordFilename(rec.record.entity_id, rec.record.rev), parked);
+    removeFileIfExists(rec.filepath);
+}
+/** Persist an updated attempt count / last error on a still-pending record. */
+export function recordAttempt(rec, meta, cwd) {
+    const updated = {
+        ...rec.record,
+        attempts: rec.record.attempts + 1,
+        last_status: meta.http_status,
+        last_error: meta.error,
+        last_attempt_at: nowISO(),
+    };
+    writeRecordAtomic(federationSubdir('outbox', cwd, 'write'), recordFilename(rec.record.entity_id, rec.record.rev), updated);
+}
+/**
+ * Startup reconcile before a drain: for each outbox record, if sent/ already
+ * holds a rev >= this one, this record is already superseded — drop it. If the
+ * SAME rev exists in sent with a different content_hash, park it (divergence).
+ */
+export function reconcileOutbox(cwd) {
+    const result = { dropped: 0, parked: 0 };
+    const sentDir = federationSubdir('sent', cwd, 'read');
+    for (const rec of listOutboxRecords(cwd)) {
+        const sentRev = sentMarkerRev(rec.record.entity_id, cwd);
+        if (sentRev < rec.record.rev)
+            continue;
+        // A sent record at >= this rev exists. If the SAME rev has a different hash, park.
+        const sameRevPath = path.join(sentDir, recordFilename(rec.record.entity_id, rec.record.rev));
+        if (fs.existsSync(sameRevPath)) {
+            try {
+                const sent = JSON.parse(fs.readFileSync(sameRevPath, 'utf-8'));
+                if (sent.content_hash !== rec.record.content_hash) {
+                    parkRecord(rec, 'reconcile: same rev already sent with a different content_hash', cwd);
+                    result.parked++;
+                    continue;
+                }
+            }
+            catch { /* fall through to drop */ }
+        }
+        removeFileIfExists(rec.filepath);
+        result.dropped++;
+    }
+    return result;
+}
+//# sourceMappingURL=federation-outbox.js.map