opencode-swarm 7.132.2 → 7.134.0

package/dist/cli/index-y3v1404y.js

@@ -0,0 +1,1625 @@
+// @bun
+import {
+  validateSwarmPath
+} from "./index-2ghkk9ve.js";
+import {
+  withEvidenceLock
+} from "./index-5nybajn9.js";
+import {
+  exports_external,
+  init_zod
+} from "./index-bpmtbmy9.js";
+import {
+  bunWrite
+} from "./index-qe3v54nb.js";
+import {
+  init_logger,
+  warn
+} from "./index-zgwm4ryv.js";
+
+// src/background/pending-delegations.ts
+init_zod();
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+init_logger();
+var BACKGROUND_DELEGATIONS_FILE = "background-delegations.jsonl";
+var BACKGROUND_DELEGATION_FALLBACK_DIR = "background-delegation-fallback";
+var BACKGROUND_CODER_RESERVATIONS_FILE = "background-coder-reservations.json";
+var MAX_LIVE_BACKGROUND_FALLBACKS = 256;
+var MAX_LIVE_BACKGROUND_CODER_RESERVATIONS = 256;
+var MAX_BACKGROUND_OBSERVED_FILES = 5000;
+var MAX_BACKGROUND_ADVISORY_CHARS = 4000;
+var MAX_RECOVERY_LEDGER_BYTES = 4 * 1024 * 1024;
+var MAX_RECOVERY_FALLBACK_BYTES = 1024 * 1024;
+var STORE_LOCK_AGENT = "background";
+var STORE_LOCK_TASK = "background-delegations";
+var FALLBACK_LOCK_TASK = "background-delegation-fallback";
+var RESERVATION_LOCK_TASK = "background-coder-reservations";
+var ADVISORY_PREPARE_LEASE_MS = 30000;
+var INGESTION_CLAIM_LEASE_MS = 30000;
+var BACKGROUND_INGESTION_LEASE_MS = 30000;
+var ResultSchema = exports_external.object({
+  text: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  chars: exports_external.number(),
+  truncated: exports_external.boolean(),
+  digest: exports_external.string(),
+  outputRef: exports_external.string().optional(),
+  outputPreviewChars: exports_external.number().optional(),
+  outputDegraded: exports_external.boolean().optional(),
+  outputArtifactError: exports_external.string().optional(),
+  transcriptIncomplete: exports_external.boolean().optional(),
+  messageCount: exports_external.number().optional()
+}).strict();
+var WorkspaceSchema = exports_external.object({
+  directory: exports_external.string(),
+  gitHead: exports_external.string().nullable(),
+  dirtyHash: exports_external.string().nullable(),
+  changedFiles: exports_external.array(exports_external.string()).nullable().optional(),
+  prHeadSha: exports_external.string().nullable(),
+  scope: exports_external.string().nullable()
+}).strict();
+var TaskChangeContextSchema = exports_external.object({
+  declaredFiles: exports_external.array(exports_external.string()).nullable(),
+  baseline: WorkspaceSchema
+}).strict();
+var WorktreeDescriptorSchema = exports_external.object({
+  callID: exports_external.string().min(1).max(256),
+  parentSessionId: exports_external.string().min(1).max(256),
+  taskId: exports_external.string().min(1).max(256),
+  planTaskId: exports_external.string().min(1).max(256).nullable(),
+  worktreePath: exports_external.string().min(1).max(4096),
+  branchName: exports_external.string().min(1).max(1024),
+  worktreeId: exports_external.string().min(1).max(256),
+  worktreeSessionId: exports_external.string().min(1).max(256),
+  mergeStrategy: exports_external.enum(["merge", "rebase", "cherry-pick"]),
+  laneIndex: exports_external.number().int().nonnegative().max(255),
+  worktreeDir: exports_external.string().min(1).max(4096).nullable()
+}).strict();
+var TerminalResultSchema = exports_external.object({
+  eventId: exports_external.string().min(1).max(256),
+  status: exports_external.enum(["completed", "error", "cancelled"]),
+  recordedAt: exports_external.number().int().nonnegative(),
+  result: ResultSchema
+}).strict();
+var NormalizedObservedFileSchema = exports_external.string().min(1).max(4096).refine((value) => normalizeObservedFile(value) === value);
+var SettlementProvenanceSchema = exports_external.object({
+  correlationId: exports_external.string().min(1).max(256),
+  parentSessionId: exports_external.string().min(1).max(256),
+  callID: exports_external.string().max(256),
+  planTaskId: exports_external.string().min(1).max(256).nullable(),
+  baseline: WorkspaceSchema,
+  worktree: WorktreeDescriptorSchema.nullable()
+}).strict();
+var SettlementOutcomeSchema = exports_external.object({
+  kind: exports_external.enum(["shared-root", "standard-worktree"]),
+  result: exports_external.enum(["ready", "merged", "unchanged", "partial", "failed"]),
+  reason: exports_external.string().min(1).max(2000).optional(),
+  sourceHeadAfterCommit: exports_external.string().min(1).max(256).nullable().optional(),
+  targetHeadBeforeMerge: exports_external.string().min(1).max(256).nullable().optional(),
+  targetHeadAfterMerge: exports_external.string().min(1).max(256).nullable().optional()
+}).strict();
+var CoderSettlementSchema = exports_external.object({
+  state: exports_external.enum(["pending", "settling", "settled", "preserved"]),
+  provenance: SettlementProvenanceSchema,
+  operationId: exports_external.string().min(1).max(256).optional(),
+  sourceHeadAfterCommit: exports_external.string().min(1).max(256).nullable().optional(),
+  targetHeadBeforeMerge: exports_external.string().min(1).max(256).nullable().optional(),
+  observedFiles: exports_external.array(NormalizedObservedFileSchema).max(MAX_BACKGROUND_OBSERVED_FILES).nullable(),
+  outcome: SettlementOutcomeSchema.optional(),
+  updatedAt: exports_external.number().int().nonnegative()
+}).strict().superRefine((value, context) => {
+  if (value.state !== "pending" && !value.operationId) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "settling, settled, and preserved states require operationId"
+    });
+  }
+  if ((value.state === "settled" || value.state === "preserved") && !value.outcome) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "terminal settlement state requires outcome"
+    });
+  }
+});
+var AdvisoryPreparationSchema = exports_external.object({
+  id: exports_external.string().min(1).max(256),
+  preparedAt: exports_external.number().int().nonnegative(),
+  leaseExpiresAt: exports_external.number().int().nonnegative()
+}).strict();
+var AdvisoryInboxSchema = exports_external.object({
+  eventId: exports_external.string().min(1).max(256),
+  parentSessionId: exports_external.string().min(1).max(256),
+  state: exports_external.enum(["pending", "delivered"]),
+  message: exports_external.string().min(1).max(MAX_BACKGROUND_ADVISORY_CHARS),
+  createdAt: exports_external.number().int().nonnegative(),
+  preparation: AdvisoryPreparationSchema.optional(),
+  deliveredAt: exports_external.number().int().nonnegative().optional()
+}).strict().superRefine((value, context) => {
+  if (value.state === "delivered" && value.deliveredAt === undefined) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "delivered advisory requires deliveredAt"
+    });
+  }
+  if (value.state === "delivered" && value.preparation !== undefined) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "delivered advisory cannot retain a preparation lease"
+    });
+  }
+});
+var DelegationIngestionSchema = exports_external.object({
+  state: exports_external.enum(["claimed", "retryable", "consumed"]),
+  attempt: exports_external.number().int().positive(),
+  updatedAt: exports_external.number().int().nonnegative(),
+  claimToken: exports_external.string().min(1).max(256),
+  leaseExpiresAt: exports_external.number().int().nonnegative().optional()
+}).strict().superRefine((value, context) => {
+  if (value.state === "claimed" && value.leaseExpiresAt === undefined) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "claimed ingestion requires a lease expiry"
+    });
+  }
+  if (value.state !== "claimed" && value.leaseExpiresAt !== undefined) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "completed ingestion cannot retain a claim lease"
+    });
+  }
+});
+var BackgroundCoderReservationSchema = exports_external.object({
+  reservationId: exports_external.string().min(1).max(256),
+  parentSessionId: exports_external.string().min(1).max(256),
+  planTaskId: exports_external.string().min(1).max(256).nullable(),
+  callID: exports_external.string().min(1).max(256),
+  state: exports_external.enum(["reserved", "bound"]),
+  correlationId: exports_external.string().min(1).max(256).nullable(),
+  createdAt: exports_external.number().int().nonnegative(),
+  updatedAt: exports_external.number().int().nonnegative()
+}).strict().superRefine((value, context) => {
+  if (value.state === "reserved" && value.correlationId !== null) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "unbound reservation cannot have a correlationId"
+    });
+  }
+  if (value.state === "bound" && value.correlationId === null) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "bound reservation requires a correlationId"
+    });
+  }
+});
+var BackgroundCoderReservationStoreSchema = exports_external.object({
+  schemaVersion: exports_external.literal(1),
+  reservations: exports_external.array(BackgroundCoderReservationSchema).max(MAX_LIVE_BACKGROUND_CODER_RESERVATIONS)
+}).strict().superRefine((value, context) => {
+  const ids = new Set;
+  for (const reservation of value.reservations) {
+    if (ids.has(reservation.reservationId)) {
+      context.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "duplicate reservationId"
+      });
+      return;
+    }
+    if (reservation.reservationId !== buildBackgroundCoderReservationId({
+      parentSessionId: reservation.parentSessionId,
+      planTaskId: reservation.planTaskId,
+      callID: reservation.callID
+    })) {
+      context.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        message: "reservationId does not match owner identity"
+      });
+      return;
+    }
+    ids.add(reservation.reservationId);
+  }
+});
+var PromptSchema = exports_external.object({
+  text: exports_external.string(),
+  chars: exports_external.number(),
+  truncated: exports_external.boolean(),
+  digest: exports_external.string()
+}).strict();
+var RecordSchema = exports_external.object({
+  schemaVersion: exports_external.union([exports_external.literal(1), exports_external.literal(2), exports_external.literal(3)]),
+  correlationId: exports_external.string().min(1),
+  jobId: exports_external.string().nullable(),
+  subagentSessionId: exports_external.string().min(1),
+  parentSessionId: exports_external.string().min(1),
+  callID: exports_external.string(),
+  normalizedAgent: exports_external.string(),
+  swarmPrefixedAgent: exports_external.string(),
+  planTaskId: exports_external.string().nullable(),
+  evidenceTaskId: exports_external.string().nullable(),
+  status: exports_external.enum([
+    "pending",
+    "running",
+    "ingestion_error",
+    "completed",
+    "error",
+    "cancelled",
+    "stale",
+    "consumed"
+  ]),
+  createdAt: exports_external.number(),
+  updatedAt: exports_external.number(),
+  batchId: exports_external.string().optional(),
+  laneId: exports_external.string().optional(),
+  mode: exports_external.string().optional(),
+  workflowLane: exports_external.string().optional(),
+  ownedWorkflowLanes: exports_external.array(exports_external.string().min(1).max(120)).min(1).max(11).optional(),
+  promptHash: exports_external.string().optional(),
+  workspace: WorkspaceSchema.optional(),
+  taskChangeContext: TaskChangeContextSchema.optional(),
+  worktree: WorktreeDescriptorSchema.optional(),
+  coderReservationId: exports_external.string().min(1).max(256).optional(),
+  prompt: PromptSchema.optional(),
+  generation: exports_external.number().optional(),
+  terminalResult: TerminalResultSchema.optional(),
+  coderSettlement: CoderSettlementSchema.optional(),
+  advisoryInbox: AdvisoryInboxSchema.optional(),
+  ingestion: DelegationIngestionSchema.optional(),
+  result: ResultSchema.optional(),
+  completedAt: exports_external.number().optional()
+}).strict();
+var FallbackArtifactSchema = exports_external.object({
+  schemaVersion: exports_external.literal(1),
+  correlationId: exports_external.string().min(1).max(256),
+  createdAt: exports_external.number().int().nonnegative(),
+  record: RecordSchema
+}).strict().superRefine((value, context) => {
+  if (value.record.correlationId !== value.correlationId || value.record.subagentSessionId !== value.correlationId || value.record.status !== "pending") {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "fallback identity/status does not match its pending record"
+    });
+  }
+});
+function storePath(directory) {
+  return validateSwarmPath(directory, BACKGROUND_DELEGATIONS_FILE);
+}
+function ensureSwarmDir(directory) {
+  fs.mkdirSync(path.resolve(directory, ".swarm"), { recursive: true });
+}
+function readDelegations(directory) {
+  let raw;
+  try {
+    raw = fs.readFileSync(storePath(directory), "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return [];
+    warn(`[background] readDelegations failed: ${err instanceof Error ? err.message : String(err)}`);
+    return [];
+  }
+  const folded = new Map;
+  for (const line of raw.split(`
+`)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+      continue;
+    let parsedJson;
+    try {
+      parsedJson = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const result = RecordSchema.safeParse(parsedJson);
+    if (!result.success)
+      continue;
+    folded.set(result.data.correlationId, result.data);
+  }
+  return [...folded.values()];
+}
+function scanDelegationsForRecovery(directory) {
+  let absolutePath;
+  try {
+    absolutePath = storePath(directory);
+    const stat = fs.statSync(absolutePath);
+    if (stat.size > MAX_RECOVERY_LEDGER_BYTES) {
+      return {
+        status: "uncertain",
+        reason: `background delegation ledger exceeds the ${MAX_RECOVERY_LEDGER_BYTES}-byte recovery bound`
+      };
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { status: "ok", owners: [] };
+    }
+    return {
+      status: "uncertain",
+      reason: `background delegation ledger metadata is unreadable: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(absolutePath, "utf-8");
+  } catch (error) {
+    return {
+      status: "uncertain",
+      reason: `background delegation ledger is unreadable: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (Buffer.byteLength(raw, "utf8") > MAX_RECOVERY_LEDGER_BYTES) {
+    return {
+      status: "uncertain",
+      reason: `background delegation ledger changed beyond the ${MAX_RECOVERY_LEDGER_BYTES}-byte recovery bound`
+    };
+  }
+  const folded = new Map;
+  let lineNumber = 0;
+  for (const line of raw.split(`
+`)) {
+    lineNumber += 1;
+    const trimmed = line.trim();
+    if (!trimmed)
+      continue;
+    let parsedJson;
+    try {
+      parsedJson = JSON.parse(trimmed);
+    } catch {
+      return {
+        status: "uncertain",
+        reason: `background delegation ledger has malformed JSON at line ${lineNumber}`
+      };
+    }
+    const parsed = RecordSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+      return {
+        status: "uncertain",
+        reason: `background delegation ledger has an invalid record at line ${lineNumber}`
+      };
+    }
+    folded.set(parsed.data.correlationId, parsed.data);
+  }
+  return { status: "ok", owners: [...folded.values()] };
+}
+function findByCorrelationId(directory, correlationId) {
+  if (!correlationId)
+    return null;
+  for (const record of readDelegations(directory)) {
+    if (record.correlationId === correlationId)
+      return record;
+  }
+  return null;
+}
+function appendRecord(directory, record) {
+  ensureSwarmDir(directory);
+  fs.appendFileSync(storePath(directory), `${JSON.stringify(record)}
+`, "utf-8");
+}
+function buildPendingRecord(input, now) {
+  return {
+    schemaVersion: input.worktree ? 3 : input.batchId ? 2 : 1,
+    correlationId: input.correlationId,
+    jobId: input.jobId,
+    subagentSessionId: input.subagentSessionId,
+    parentSessionId: input.parentSessionId,
+    callID: input.callID,
+    normalizedAgent: input.normalizedAgent,
+    swarmPrefixedAgent: input.swarmPrefixedAgent,
+    planTaskId: input.planTaskId,
+    evidenceTaskId: input.evidenceTaskId,
+    status: "pending",
+    createdAt: now,
+    updatedAt: now,
+    ...input.batchId ? { batchId: input.batchId } : {},
+    ...input.laneId ? { laneId: input.laneId } : {},
+    ...input.mode ? { mode: input.mode } : {},
+    ...input.workflowLane ? { workflowLane: input.workflowLane } : {},
+    ...input.ownedWorkflowLanes?.length ? { ownedWorkflowLanes: [...input.ownedWorkflowLanes] } : {},
+    ...input.promptHash ? { promptHash: input.promptHash } : {},
+    ...input.workspace ? { workspace: input.workspace } : {},
+    ...input.taskChangeContext ? { taskChangeContext: input.taskChangeContext } : {},
+    ...input.worktree ? { worktree: input.worktree } : {},
+    ...input.coderReservationId ? { coderReservationId: input.coderReservationId } : {},
+    ...input.prompt ? { prompt: input.prompt } : {},
+    ...input.generation !== undefined ? { generation: input.generation } : {}
+  };
+}
+async function recordPendingDelegation(directory, input, options = {}) {
+  const now = Date.now();
+  const record = buildPendingRecord(input, now);
+  const parsedRecord = RecordSchema.safeParse(record);
+  if (!parsedRecord.success) {
+    warn("[background] recordPendingDelegation rejected invalid input");
+    return null;
+  }
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      if (options.staleTimeoutMs && options.staleTimeoutMs > 0) {
+        sweepStaleLocked(directory, options.staleTimeoutMs, now);
+      }
+      appendRecord(directory, parsedRecord.data);
+    });
+    return parsedRecord.data;
+  } catch (err) {
+    warn(`[background] recordPendingDelegation failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+function buildPromptSnapshot(text, maxChars) {
+  const boundedMax = Math.max(0, Math.min(maxChars, 20000));
+  const truncated = text.length > boundedMax;
+  const bounded = truncated ? text.slice(0, boundedMax) : text;
+  return {
+    text: bounded,
+    chars: text.length,
+    truncated,
+    digest: createHash("sha256").update(text).digest("hex")
+  };
+}
+async function appendDelegationTransition(directory, correlationId, transition) {
+  const now = Date.now();
+  try {
+    let next = null;
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current)
+        return;
+      if (isTerminal(current.status) && transition.status !== "consumed" && transition.status !== "ingestion_error" && !(current.status === "completed" && transition.status === "stale")) {
+        next = current;
+        return;
+      }
+      next = {
+        ...current,
+        schemaVersion: current.schemaVersion === 1 ? 2 : current.schemaVersion,
+        status: transition.status,
+        updatedAt: now,
+        ...transition.completedAt !== undefined ? { completedAt: transition.completedAt } : transition.status === "completed" || transition.status === "error" ? { completedAt: now } : {},
+        ...transition.result ? { result: transition.result } : {}
+      };
+      appendRecord(directory, next);
+    });
+    return next;
+  } catch (err) {
+    warn(`[background] appendDelegationTransition failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+function buildBackgroundCompletionEventId(input) {
+  const canonical = JSON.stringify([
+    input.correlationId,
+    input.jobId,
+    input.status,
+    input.resultDigest
+  ]);
+  return `bgc1:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function sameTerminalEvent(left, right) {
+  return left.eventId === right.eventId && left.status === right.status && sameJson(left.result, right.result);
+}
+function settlementProvenanceFor(record) {
+  const baseline = record.taskChangeContext?.baseline;
+  if (!baseline)
+    return null;
+  return {
+    correlationId: record.correlationId,
+    parentSessionId: record.parentSessionId,
+    callID: record.callID,
+    planTaskId: record.planTaskId,
+    baseline,
+    worktree: record.worktree ?? null
+  };
+}
+function terminalDisposition(record) {
+  if (record.status === "consumed")
+    return "consumed";
+  if (record.coderSettlement?.state === "settling")
+    return "resume_settlement";
+  if (record.coderSettlement?.state === "preserved")
+    return "preserved";
+  if (record.status === "ingestion_error")
+    return "retry_ingestion";
+  return "duplicate";
+}
+async function claimTerminalResult(directory, correlationId, terminalResult) {
+  const parsedTerminal = TerminalResultSchema.safeParse(terminalResult);
+  if (!correlationId || !parsedTerminal.success)
+    return null;
+  let claim = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current)
+        return;
+      if (current.terminalResult) {
+        if (!sameTerminalEvent(current.terminalResult, parsedTerminal.data)) {
+          warn(`[background] claimTerminalResult: different terminal event for ` + `correlationId=${correlationId}; ` + `existing={status: ${current.terminalResult.status}, eventId: ${current.terminalResult.eventId}} ` + `incoming={status: ${parsedTerminal.data.status}, eventId: ${parsedTerminal.data.eventId}}; ` + `rejected`);
+          return;
+        }
+        claim = {
+          disposition: terminalDisposition(current),
+          record: current
+        };
+        return;
+      }
+      if (current.status !== "pending" && current.status !== "running") {
+        return;
+      }
+      let coderSettlement = current.coderSettlement;
+      if (current.normalizedAgent === "coder" && !coderSettlement) {
+        const provenance = settlementProvenanceFor(current);
+        if (provenance) {
+          coderSettlement = {
+            state: "pending",
+            provenance,
+            observedFiles: null,
+            updatedAt: parsedTerminal.data.recordedAt
+          };
+        }
+      }
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        status: parsedTerminal.data.status,
+        terminalResult: parsedTerminal.data,
+        result: parsedTerminal.data.result,
+        completedAt: parsedTerminal.data.recordedAt,
+        updatedAt: parsedTerminal.data.recordedAt,
+        ...coderSettlement ? { coderSettlement } : {}
+      };
+      if (!RecordSchema.safeParse(next).success)
+        return;
+      appendRecord(directory, next);
+      claim = { disposition: "claimed", record: next };
+    });
+    return claim;
+  } catch (err) {
+    warn(`[background] claimTerminalResult failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function claimCoderSettlement(directory, correlationId, operationId, input = {}) {
+  if (!correlationId || !operationId || operationId.length > 256)
+    return null;
+  let claim = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current || current.normalizedAgent !== "coder" || current.terminalResult?.status !== "completed") {
+        return;
+      }
+      const provenance = settlementProvenanceFor(current);
+      if (!provenance)
+        return;
+      const existing = current.coderSettlement ?? {
+        state: "pending",
+        provenance,
+        observedFiles: null,
+        updatedAt: current.updatedAt
+      };
+      if (existing.state === "settled" || existing.state === "preserved") {
+        claim = {
+          disposition: existing.state,
+          record: current
+        };
+        return;
+      }
+      if (existing.state === "settling" && existing.operationId !== operationId) {
+        return;
+      }
+      if (existing.sourceHeadAfterCommit !== undefined && input.sourceHeadAfterCommit !== undefined && existing.sourceHeadAfterCommit !== input.sourceHeadAfterCommit) {
+        return;
+      }
+      if (existing.targetHeadBeforeMerge !== undefined && input.targetHeadBeforeMerge !== undefined && existing.targetHeadBeforeMerge !== input.targetHeadBeforeMerge) {
+        return;
+      }
+      const settlement = {
+        ...existing,
+        state: "settling",
+        operationId,
+        ...input.sourceHeadAfterCommit !== undefined ? { sourceHeadAfterCommit: input.sourceHeadAfterCommit } : {},
+        ...input.targetHeadBeforeMerge !== undefined ? { targetHeadBeforeMerge: input.targetHeadBeforeMerge } : {},
+        updatedAt: Date.now()
+      };
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        coderSettlement: settlement,
+        updatedAt: settlement.updatedAt
+      };
+      if (!RecordSchema.safeParse(next).success)
+        return;
+      appendRecord(directory, next);
+      claim = {
+        disposition: existing.state === "settling" ? "resume" : "claimed",
+        record: next
+      };
+    });
+    return claim;
+  } catch (err) {
+    warn(`[background] claimCoderSettlement failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+function normalizeObservedFile(value) {
+  if (typeof value !== "string")
+    return null;
+  const trimmed = value.trim().replace(/\\/g, "/");
+  if (trimmed.length === 0 || trimmed.length > 4096 || trimmed.includes("\x00") || path.posix.isAbsolute(trimmed) || /^[A-Za-z]:\//.test(trimmed)) {
+    return null;
+  }
+  const normalized = path.posix.normalize(trimmed).replace(/^\.\//, "");
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.endsWith("/")) {
+    return null;
+  }
+  return normalized;
+}
+function normalizeBackgroundObservedFiles(files) {
+  if (!Array.isArray(files) || files.length > MAX_BACKGROUND_OBSERVED_FILES) {
+    return null;
+  }
+  const normalized = new Set;
+  for (const file of files) {
+    const candidate = normalizeObservedFile(file);
+    if (!candidate)
+      return null;
+    normalized.add(candidate);
+  }
+  return [...normalized].sort();
+}
+async function updateCoderSettlement(directory, correlationId, input) {
+  if (!correlationId || !input.operationId)
+    return null;
+  let result = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      const existing = current?.coderSettlement;
+      if (!current || !existing)
+        return;
+      if (existing.state === "settled" || existing.state === "preserved") {
+        result = current;
+        return;
+      }
+      if (existing.state !== "settling" || existing.operationId !== input.operationId) {
+        return;
+      }
+      if (existing.sourceHeadAfterCommit !== undefined && input.sourceHeadAfterCommit !== undefined && existing.sourceHeadAfterCommit !== input.sourceHeadAfterCommit) {
+        return;
+      }
+      if (existing.targetHeadBeforeMerge !== undefined && input.targetHeadBeforeMerge !== undefined && existing.targetHeadBeforeMerge !== input.targetHeadBeforeMerge) {
+        return;
+      }
+      if ((input.state === "settled" || input.state === "preserved") && !input.outcome) {
+        return;
+      }
+      if (input.outcome && (existing.provenance.worktree && input.outcome.kind !== "standard-worktree" || !existing.provenance.worktree && input.outcome.kind !== "shared-root")) {
+        return;
+      }
+      if (input.state === "settled" && input.outcome && (input.outcome.result === "partial" || input.outcome.result === "failed")) {
+        return;
+      }
+      if (input.state === "preserved" && input.outcome && input.outcome.result !== "partial" && input.outcome.result !== "failed") {
+        return;
+      }
+      let observedFiles = existing.observedFiles;
+      if (input.observedFiles !== undefined) {
+        if (input.observedFiles === null) {
+          observedFiles = null;
+        } else {
+          const normalized = normalizeBackgroundObservedFiles(input.observedFiles);
+          if (!normalized)
+            return;
+          observedFiles = normalized;
+        }
+      }
+      if (input.state === "settled" && observedFiles === null)
+        return;
+      const updatedAt = Date.now();
+      const settlement = {
+        ...existing,
+        state: input.state,
+        ...input.sourceHeadAfterCommit !== undefined ? { sourceHeadAfterCommit: input.sourceHeadAfterCommit } : {},
+        ...input.targetHeadBeforeMerge !== undefined ? { targetHeadBeforeMerge: input.targetHeadBeforeMerge } : {},
+        observedFiles,
+        ...input.outcome ? { outcome: input.outcome } : {},
+        updatedAt
+      };
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        coderSettlement: settlement,
+        updatedAt
+      };
+      if (!RecordSchema.safeParse(next).success)
+        return;
+      appendRecord(directory, next);
+      result = next;
+    });
+    return result;
+  } catch (err) {
+    warn(`[background] updateCoderSettlement failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function claimDelegationIngestion(directory, correlationId, options) {
+  if (!correlationId || !options.claimantId)
+    return null;
+  const now = options.now ?? Date.now();
+  const leaseMs = Math.max(1000, Math.min(options.leaseMs ?? INGESTION_CLAIM_LEASE_MS, 5 * 60000));
+  let claim = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current?.terminalResult)
+        return;
+      if (current.status === "consumed") {
+        claim = { disposition: "consumed", record: current };
+        return;
+      }
+      if (current.ingestion?.state === "claimed" && (current.ingestion.leaseExpiresAt ?? Number.MAX_SAFE_INTEGER) > now) {
+        claim = { disposition: "busy", record: current };
+        return;
+      }
+      if (current.coderSettlement?.state === "preserved") {
+        claim = { disposition: "preserved", record: current };
+        return;
+      }
+      if (current.terminalResult.status !== "completed" || current.normalizedAgent === "coder" && current.coderSettlement?.state !== "settled") {
+        claim = { disposition: "not_ready", record: current };
+        return;
+      }
+      if (current.status !== "completed" && current.status !== "ingestion_error") {
+        claim = { disposition: "not_ready", record: current };
+        return;
+      }
+      const disposition = current.status === "ingestion_error" || current.ingestion?.state === "claimed" ? "retry" : "claimed";
+      const attempt = (current.ingestion?.attempt ?? 0) + 1;
+      const claimToken = createHash("sha256").update(JSON.stringify([correlationId, options.claimantId, attempt, now])).digest("hex");
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        ingestion: {
+          state: "claimed",
+          attempt,
+          updatedAt: now,
+          claimToken,
+          leaseExpiresAt: now + leaseMs
+        },
+        updatedAt: now
+      };
+      appendRecord(directory, next);
+      claim = { disposition, record: next };
+    });
+    return claim;
+  } catch (err) {
+    warn(`[background] claimDelegationIngestion failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function recordDelegationIngestionResult(directory, correlationId, claimToken, success, options = {}) {
+  if (!correlationId || !claimToken)
+    return null;
+  let result = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current)
+        return;
+      if (success && current.status === "consumed" && current.ingestion?.state === "consumed" && current.ingestion.claimToken === claimToken || !success && current.status === "ingestion_error" && current.ingestion?.state === "retryable" && current.ingestion.claimToken === claimToken) {
+        result = current;
+        return;
+      }
+      if (current.ingestion?.state !== "claimed" || current.ingestion.claimToken !== claimToken || (current.ingestion.leaseExpiresAt ?? 0) <= (options.now ?? Date.now()))
+        return;
+      const updatedAt = options.now ?? Date.now();
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        status: success ? "consumed" : "ingestion_error",
+        ingestion: {
+          state: success ? "consumed" : "retryable",
+          attempt: current.ingestion.attempt,
+          claimToken,
+          updatedAt
+        },
+        updatedAt
+      };
+      appendRecord(directory, next);
+      result = next;
+    });
+    return result;
+  } catch (err) {
+    warn(`[background] recordDelegationIngestionResult failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function putPendingBackgroundAdvisory(directory, correlationId, input) {
+  const createdAt = input.createdAt ?? Date.now();
+  const parsed = AdvisoryInboxSchema.safeParse({
+    eventId: input.eventId,
+    parentSessionId: input.parentSessionId,
+    state: "pending",
+    message: input.message,
+    createdAt
+  });
+  if (!correlationId || !parsed.success)
+    return null;
+  let result = null;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const current = findByCorrelationId(directory, correlationId);
+      if (!current?.terminalResult || current.terminalResult.eventId !== parsed.data.eventId || current.parentSessionId !== parsed.data.parentSessionId) {
+        return;
+      }
+      if (current.advisoryInbox) {
+        if (current.advisoryInbox.eventId === parsed.data.eventId && current.advisoryInbox.parentSessionId === parsed.data.parentSessionId && current.advisoryInbox.message === parsed.data.message) {
+          result = current.advisoryInbox;
+        }
+        return;
+      }
+      const next = {
+        ...current,
+        schemaVersion: 3,
+        advisoryInbox: parsed.data,
+        updatedAt: createdAt
+      };
+      appendRecord(directory, next);
+      result = parsed.data;
+    });
+    return result;
+  } catch (err) {
+    warn(`[background] putPendingBackgroundAdvisory failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function preparePendingBackgroundAdvisories(directory, parentSessionId, options) {
+  if (!parentSessionId || !options.preparationId)
+    return [];
+  const now = options.now ?? Date.now();
+  const leaseMs = Math.max(1000, Math.min(options.leaseMs ?? ADVISORY_PREPARE_LEASE_MS, 5 * 60000));
+  const prepared = [];
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      for (const current of readDelegations(directory)) {
+        if (prepared.length >= 1)
+          break;
+        const advisory = current.advisoryInbox;
+        if (!advisory || advisory.parentSessionId !== parentSessionId || advisory.state !== "pending") {
+          continue;
+        }
+        if (advisory.preparation && advisory.preparation.id !== options.preparationId && advisory.preparation.leaseExpiresAt > now) {
+          continue;
+        }
+        const nextAdvisory = {
+          ...advisory,
+          preparation: {
+            id: options.preparationId,
+            preparedAt: now,
+            leaseExpiresAt: now + leaseMs
+          }
+        };
+        const next = {
+          ...current,
+          schemaVersion: 3,
+          advisoryInbox: nextAdvisory,
+          updatedAt: now
+        };
+        appendRecord(directory, next);
+        prepared.push(nextAdvisory);
+      }
+    });
+    return prepared;
+  } catch (err) {
+    warn(`[background] preparePendingBackgroundAdvisories failed: ${err instanceof Error ? err.message : String(err)}`);
+    return [];
+  }
+}
+async function releaseBackgroundAdvisoryPreparation(directory, parentSessionId, preparationId, eventIds) {
+  const uniqueEventIds = [...new Set(eventIds)];
+  if (!parentSessionId || !preparationId || uniqueEventIds.length !== 1) {
+    return false;
+  }
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const byEvent = new Map;
+      for (const current of readDelegations(directory)) {
+        const advisory = current.advisoryInbox;
+        if (advisory?.parentSessionId === parentSessionId && uniqueEventIds.includes(advisory.eventId)) {
+          byEvent.set(advisory.eventId, current);
+        }
+      }
+      for (const eventId of uniqueEventIds) {
+        const advisory = byEvent.get(eventId)?.advisoryInbox;
+        if (!advisory || advisory.state !== "pending" || advisory.preparation?.id !== preparationId) {
+          return false;
+        }
+      }
+      for (const eventId of uniqueEventIds) {
+        const current = byEvent.get(eventId);
+        if (!current?.advisoryInbox)
+          return false;
+        const now = Date.now();
+        const next = {
+          ...current,
+          schemaVersion: 3,
+          advisoryInbox: {
+            ...current.advisoryInbox,
+            preparation: undefined
+          },
+          updatedAt: now
+        };
+        appendRecord(directory, next);
+      }
+      return true;
+    });
+  } catch (err) {
+    warn(`[background] releasePreparedBackgroundAdvisories failed: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+async function acknowledgeObservedBackgroundAdvisories(directory, parentSessionId, observedTexts) {
+  if (!parentSessionId || observedTexts.length === 0)
+    return 0;
+  let acknowledged = 0;
+  try {
+    await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+      const now = Date.now();
+      for (const current of readDelegations(directory)) {
+        const advisory = current.advisoryInbox;
+        if (!advisory || advisory.parentSessionId !== parentSessionId || advisory.state !== "pending" || !observedTexts.some((text) => {
+          const advisoryBlock = text.match(/\[ADVISORIES\]([\s\S]*?)\[\/ADVISORIES\]/);
+          if (advisoryBlock) {
+            return advisoryBlock[1].split(`
+---
+`).some((entry) => entry.trim() === advisory.message);
+          }
+          return text.includes(advisory.message);
+        })) {
+          continue;
+        }
+        const next = {
+          ...current,
+          schemaVersion: 3,
+          advisoryInbox: {
+            ...advisory,
+            state: "delivered",
+            deliveredAt: now,
+            preparation: undefined
+          },
+          updatedAt: now
+        };
+        appendRecord(directory, next);
+        acknowledged += 1;
+      }
+    });
+    return acknowledged;
+  } catch (err) {
+    warn(`[background] acknowledgeObservedBackgroundAdvisories failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 0;
+  }
+}
+async function releasePreparedBackgroundAdvisories(directory, parentSessionId, preparationId, eventIds) {
+  return releaseBackgroundAdvisoryPreparation(directory, parentSessionId, preparationId, eventIds);
+}
+function findByBatchId(directory, batchId, opts) {
+  if (!batchId)
+    return [];
+  return readDelegations(directory).filter((record) => record.batchId === batchId && (opts?.parentSessionId === undefined || record.parentSessionId === opts.parentSessionId));
+}
+function findOpenAsyncLaneBatches(directory) {
+  return readDelegations(directory).filter((record) => record.batchId !== undefined && (record.status === "pending" || record.status === "running"));
+}
+function isTerminal(status) {
+  return status === "completed" || status === "error" || status === "cancelled" || status === "stale" || status === "consumed";
+}
+function sweepStaleLocked(directory, timeoutMs, now) {
+  let swept = 0;
+  for (const record of readDelegations(directory)) {
+    if (record.status !== "pending" && record.status !== "running" && record.status !== "ingestion_error")
+      continue;
+    if (now - record.updatedAt <= timeoutMs)
+      continue;
+    appendRecord(directory, {
+      ...record,
+      status: "stale",
+      updatedAt: now
+    });
+    swept += 1;
+  }
+  return swept;
+}
+async function sweepStaleDelegations(directory, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return 0;
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => sweepStaleLocked(directory, timeoutMs, Date.now()));
+  } catch (err) {
+    warn(`[background] sweepStaleDelegations failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 0;
+  }
+}
+function fallbackRelativePath(correlationId) {
+  const digest = createHash("sha256").update(correlationId).digest("hex");
+  return path.join(BACKGROUND_DELEGATION_FALLBACK_DIR, `${digest}.json`);
+}
+function fallbackPath(directory, correlationId) {
+  return validateSwarmPath(directory, fallbackRelativePath(correlationId));
+}
+function fallbackDirectoryPath(directory) {
+  return path.dirname(validateSwarmPath(directory, path.join(BACKGROUND_DELEGATION_FALLBACK_DIR, ".containment-anchor")));
+}
+async function readFallbackFile(directory, correlationId) {
+  for (let attempt = 0;attempt < 5; attempt++) {
+    try {
+      const raw = await fs.promises.readFile(fallbackPath(directory, correlationId), "utf-8");
+      const parsedJson = JSON.parse(raw);
+      const parsed = FallbackArtifactSchema.safeParse(parsedJson);
+      if (!parsed.success || parsed.data.correlationId !== correlationId) {
+        return null;
+      }
+      return parsed.data;
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT" && attempt < 4) {
+        await new Promise((resolve2) => setTimeout(resolve2, 10));
+        continue;
+      }
+      return null;
+    }
+  }
+  return null;
+}
+async function readDelegationFallback(directory, correlationId) {
+  if (!correlationId)
+    return null;
+  return readFallbackFile(directory, correlationId);
+}
+async function listDelegationFallbacks(directory) {
+  let entries;
+  try {
+    entries = fs.readdirSync(fallbackDirectoryPath(directory), {
+      withFileTypes: true
+    }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).slice(0, MAX_LIVE_BACKGROUND_FALLBACKS);
+  } catch {
+    return [];
+  }
+  const artifacts = [];
+  for (const entry of entries) {
+    try {
+      const raw = await fs.promises.readFile(path.join(fallbackDirectoryPath(directory), entry.name), "utf-8");
+      const parsed = FallbackArtifactSchema.safeParse(JSON.parse(raw));
+      if (parsed.success)
+        artifacts.push(parsed.data);
+    } catch {}
+  }
+  return artifacts;
+}
+async function scanDelegationFallbacksForRecovery(directory) {
+  let fallbackDir;
+  let entries;
+  try {
+    fallbackDir = fallbackDirectoryPath(directory);
+    entries = fs.readdirSync(fallbackDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".json"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { status: "ok", owners: [] };
+    }
+    return {
+      status: "uncertain",
+      reason: `background fallback directory is unreadable: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (entries.length > MAX_LIVE_BACKGROUND_FALLBACKS) {
+    return {
+      status: "uncertain",
+      reason: `background fallback owner count exceeds the ${MAX_LIVE_BACKGROUND_FALLBACKS}-artifact safety bound`
+    };
+  }
+  const artifacts = [];
+  for (const entry of entries) {
+    const artifactPath = path.join(fallbackDir, entry.name);
+    let raw;
+    try {
+      const stat = fs.statSync(artifactPath);
+      if (stat.size > MAX_RECOVERY_FALLBACK_BYTES) {
+        return {
+          status: "uncertain",
+          reason: `background fallback artifact "${entry.name}" exceeds the recovery size bound`
+        };
+      }
+      raw = await fs.promises.readFile(artifactPath, "utf-8");
+    } catch (error) {
+      return {
+        status: "uncertain",
+        reason: `background fallback artifact "${entry.name}" is unreadable: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    if (Buffer.byteLength(raw, "utf8") > MAX_RECOVERY_FALLBACK_BYTES) {
+      return {
+        status: "uncertain",
+        reason: `background fallback artifact "${entry.name}" changed beyond the recovery size bound`
+      };
+    }
+    let parsedJson;
+    try {
+      parsedJson = JSON.parse(raw);
+    } catch {
+      return {
+        status: "uncertain",
+        reason: `background fallback artifact "${entry.name}" has malformed JSON`
+      };
+    }
+    const parsed = FallbackArtifactSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+      return {
+        status: "uncertain",
+        reason: `background fallback artifact "${entry.name}" has an invalid owner record`
+      };
+    }
+    artifacts.push(parsed.data);
+  }
+  return { status: "ok", owners: artifacts };
+}
+function countFallbackFiles(directory) {
+  try {
+    return fs.readdirSync(fallbackDirectoryPath(directory), {
+      withFileTypes: true
+    }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).length;
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return 0;
+    return MAX_LIVE_BACKGROUND_FALLBACKS;
+  }
+}
+async function writeDelegationFallback(directory, input, options = {}) {
+  const now = Date.now();
+  const record = {
+    ...buildPendingRecord(input, now),
+    schemaVersion: 3
+  };
+  const artifact = {
+    schemaVersion: 1,
+    correlationId: input.correlationId,
+    createdAt: now,
+    record
+  };
+  const parsed = FallbackArtifactSchema.safeParse(artifact);
+  if (!parsed.success)
+    return null;
+  const requestedCap = Math.floor(Math.max(1, options.maxLive ?? MAX_LIVE_BACKGROUND_FALLBACKS));
+  const maxLive = Math.min(requestedCap, MAX_LIVE_BACKGROUND_FALLBACKS);
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_DELEGATION_FALLBACK_DIR, STORE_LOCK_AGENT, FALLBACK_LOCK_TASK, async () => {
+      const existing = await readFallbackFile(directory, input.correlationId);
+      if (existing) {
+        return samePendingRecord(existing.record, parsed.data.record) ? existing : null;
+      }
+      if (countFallbackFiles(directory) >= maxLive)
+        return null;
+      const absPath = fallbackPath(directory, input.correlationId);
+      fs.mkdirSync(path.dirname(absPath), { recursive: true });
+      await bunWrite(absPath, `${JSON.stringify(parsed.data)}
+`);
+      return parsed.data;
+    });
+  } catch (err) {
+    warn(`[background] writeDelegationFallback failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function removeDelegationFallback(directory, correlationId) {
+  if (!correlationId)
+    return false;
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_DELEGATION_FALLBACK_DIR, STORE_LOCK_AGENT, FALLBACK_LOCK_TASK, async () => {
+      try {
+        await fs.promises.unlink(fallbackPath(directory, correlationId));
+        return true;
+      } catch (err) {
+        return err.code === "ENOENT";
+      }
+    });
+  } catch (err) {
+    warn(`[background] removeDelegationFallback failed: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+async function findDelegationForCompletion(directory, correlationId) {
+  if (!correlationId)
+    return null;
+  const primary = findByCorrelationId(directory, correlationId);
+  if (primary)
+    return { source: "primary", record: primary };
+  const fallback = await readDelegationFallback(directory, correlationId);
+  return fallback ? { source: "fallback", record: fallback.record, fallback } : null;
+}
+function samePromotionIdentity(primary, fallback) {
+  return primary.correlationId === fallback.correlationId && primary.subagentSessionId === fallback.subagentSessionId && primary.parentSessionId === fallback.parentSessionId && primary.callID === fallback.callID && primary.planTaskId === fallback.planTaskId && primary.coderReservationId === fallback.coderReservationId && sameJson(primary.worktree ?? null, fallback.worktree ?? null) && sameJson(primary.taskChangeContext ?? null, fallback.taskChangeContext ?? null);
+}
+function samePendingRecord(left, right) {
+  const {
+    createdAt: _leftCreatedAt,
+    updatedAt: _leftUpdatedAt,
+    ...leftIdentity
+  } = left;
+  const {
+    createdAt: _rightCreatedAt,
+    updatedAt: _rightUpdatedAt,
+    ...rightIdentity
+  } = right;
+  return sameJson(leftIdentity, rightIdentity);
+}
+async function promoteDelegationFallback(directory, correlationId) {
+  if (!correlationId)
+    return null;
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_DELEGATION_FALLBACK_DIR, STORE_LOCK_AGENT, FALLBACK_LOCK_TASK, async () => {
+      const fallback = await readFallbackFile(directory, correlationId);
+      if (!fallback) {
+        const primary = findByCorrelationId(directory, correlationId);
+        return primary ? { source: "primary", record: primary } : null;
+      }
+      let promoted = null;
+      await withEvidenceLock(directory, BACKGROUND_DELEGATIONS_FILE, STORE_LOCK_AGENT, STORE_LOCK_TASK, async () => {
+        const current = findByCorrelationId(directory, correlationId);
+        if (current) {
+          if (samePromotionIdentity(current, fallback.record)) {
+            promoted = current;
+          }
+          return;
+        }
+        appendRecord(directory, fallback.record);
+        promoted = fallback.record;
+      });
+      if (!promoted)
+        return null;
+      try {
+        await fs.promises.unlink(fallbackPath(directory, correlationId));
+      } catch (err) {
+        if (err.code !== "ENOENT") {
+          return null;
+        }
+      }
+      return { source: "primary", record: promoted };
+    });
+  } catch (err) {
+    warn(`[background] promoteDelegationFallback failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+var MAX_BACKGROUND_CODER_RESERVATION_STORE_BYTES = 2 * 1024 * 1024;
+function reservationStorePath(directory) {
+  return validateSwarmPath(directory, BACKGROUND_CODER_RESERVATIONS_FILE);
+}
+function buildBackgroundCoderReservationId(input) {
+  const ownerIdentity = input.planTaskId === null ? ["call", input.parentSessionId, input.callID] : ["task", input.parentSessionId, input.planTaskId];
+  return `bgcr1:${createHash("sha256").update(JSON.stringify(ownerIdentity)).digest("hex")}`;
+}
+function scanBackgroundCoderReservationsForAdmission(directory) {
+  let absolutePath;
+  let raw;
+  try {
+    absolutePath = reservationStorePath(directory);
+    const stat = fs.statSync(absolutePath);
+    if (stat.size > MAX_BACKGROUND_CODER_RESERVATION_STORE_BYTES) {
+      return {
+        status: "uncertain",
+        reason: `background coder reservation store exceeds the ${MAX_BACKGROUND_CODER_RESERVATION_STORE_BYTES}-byte safety bound`
+      };
+    }
+    raw = fs.readFileSync(absolutePath, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { status: "ok", reservations: [] };
+    }
+    return {
+      status: "uncertain",
+      reason: `background coder reservation store is unreadable: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (Buffer.byteLength(raw, "utf8") > MAX_BACKGROUND_CODER_RESERVATION_STORE_BYTES) {
+    return {
+      status: "uncertain",
+      reason: "background coder reservation store changed beyond its safety bound"
+    };
+  }
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch {
+    return {
+      status: "uncertain",
+      reason: "background coder reservation store contains malformed JSON"
+    };
+  }
+  const parsed = BackgroundCoderReservationStoreSchema.safeParse(parsedJson);
+  if (!parsed.success) {
+    return {
+      status: "uncertain",
+      reason: "background coder reservation store failed strict schema validation"
+    };
+  }
+  return { status: "ok", reservations: parsed.data.reservations };
+}
+async function writeBackgroundCoderReservations(directory, reservations) {
+  const parsed = BackgroundCoderReservationStoreSchema.safeParse({
+    schemaVersion: 1,
+    reservations
+  });
+  if (!parsed.success)
+    return false;
+  try {
+    await bunWrite(reservationStorePath(directory), `${JSON.stringify(parsed.data)}
+`);
+    return true;
+  } catch (error) {
+    warn(`[background] reservation write failed: ${error instanceof Error ? error.message : String(error)}`);
+    return false;
+  }
+}
+function reservationOwnerKey(input) {
+  return input.planTaskId === null ? `call:${input.parentSessionId}:${input.callID}` : `task:${input.parentSessionId}:${input.planTaskId}`;
+}
+function isActiveCoderOwner(record) {
+  if (record.normalizedAgent !== "coder" || record.status === "consumed") {
+    return false;
+  }
+  if (record.status === "pending" || record.status === "running" || record.status === "completed" || record.status === "ingestion_error") {
+    return true;
+  }
+  if (record.coderSettlement?.state === "preserved")
+    return true;
+  return record.worktree !== undefined;
+}
+async function scanDurableCoderOwners(directory) {
+  const fallbackScan = await scanDelegationFallbacksForRecovery(directory);
+  if (fallbackScan.status === "uncertain")
+    return fallbackScan;
+  const primaryScan = scanDelegationsForRecovery(directory);
+  if (primaryScan.status === "uncertain")
+    return primaryScan;
+  const recordsByCorrelation = new Map;
+  for (const artifact of fallbackScan.owners) {
+    recordsByCorrelation.set(artifact.correlationId, artifact.record);
+  }
+  const primaryByCorrelation = new Map;
+  const primaryByReservationId = new Map;
+  for (const record of primaryScan.owners) {
+    primaryByCorrelation.set(record.correlationId, record);
+    if (record.coderReservationId) {
+      const owners = primaryByReservationId.get(record.coderReservationId) ?? [];
+      owners.push(record);
+      primaryByReservationId.set(record.coderReservationId, owners);
+    }
+    recordsByCorrelation.set(record.correlationId, record);
+  }
+  return {
+    status: "ok",
+    recordsByCorrelation,
+    primaryByCorrelation,
+    primaryByReservationId
+  };
+}
+function exactReservationOwnerCoordinates(reservation, record) {
+  return record.coderReservationId === reservation.reservationId && record.parentSessionId === reservation.parentSessionId && record.planTaskId === reservation.planTaskId && record.callID === reservation.callID;
+}
+function exactReservationRecordMatch(reservation, record) {
+  return exactReservationOwnerCoordinates(reservation, record) && record.correlationId === reservation.correlationId;
+}
+function findExactPrimaryReservationOwner(reservation, ownerScan) {
+  if (reservation.correlationId !== null) {
+    const primary = ownerScan.primaryByCorrelation.get(reservation.correlationId);
+    return primary && exactReservationRecordMatch(reservation, primary) ? primary : null;
+  }
+  const exactOwners = (ownerScan.primaryByReservationId.get(reservation.reservationId) ?? []).filter((record) => exactReservationOwnerCoordinates(reservation, record));
+  return exactOwners.length === 1 ? exactOwners[0] : null;
+}
+function hasProvenReleasedReservationOwner(record) {
+  if (record.status === "consumed")
+    return true;
+  return record.worktree === undefined && (record.status === "error" || record.status === "cancelled") && record.terminalResult?.status === record.status;
+}
+function validateReservationIdentity(input) {
+  return typeof input.parentSessionId === "string" && input.parentSessionId.length > 0 && input.parentSessionId.length <= 256 && input.parentSessionId.trim() === input.parentSessionId && typeof input.callID === "string" && input.callID.length > 0 && input.callID.length <= 256 && input.callID.trim() === input.callID && (input.planTaskId === null || typeof input.planTaskId === "string" && input.planTaskId.length > 0 && input.planTaskId.length <= 256 && input.planTaskId.trim() === input.planTaskId);
+}
+async function reserveBackgroundCoderSlot(directory, input) {
+  if (!validateReservationIdentity(input) || !Number.isInteger(input.maxConcurrent) || input.maxConcurrent < 1 || input.maxConcurrent > 64 || (input.occupiedTaskIds?.length ?? 0) > 64) {
+    return { ok: false, reason: "invalid" };
+  }
+  const occupiedTaskIds = new Set;
+  for (const taskId of input.occupiedTaskIds ?? []) {
+    if (typeof taskId !== "string" || taskId.length === 0 || taskId.length > 256 || taskId.trim() !== taskId) {
+      return { ok: false, reason: "invalid" };
+    }
+    occupiedTaskIds.add(taskId);
+  }
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_CODER_RESERVATIONS_FILE, STORE_LOCK_AGENT, RESERVATION_LOCK_TASK, async () => {
+      const reservationScan = scanBackgroundCoderReservationsForAdmission(directory);
+      if (reservationScan.status === "uncertain") {
+        return {
+          ok: false,
+          reason: "uncertain",
+          detail: reservationScan.reason
+        };
+      }
+      const ownerScan = await scanDurableCoderOwners(directory);
+      if (ownerScan.status === "uncertain") {
+        return {
+          ok: false,
+          reason: "uncertain",
+          detail: ownerScan.reason
+        };
+      }
+      const reservations = reservationScan.reservations.filter((reservation2) => {
+        const primary = findExactPrimaryReservationOwner(reservation2, ownerScan);
+        return !(primary && hasProvenReleasedReservationOwner(primary));
+      });
+      if (reservations.length !== reservationScan.reservations.length && !await writeBackgroundCoderReservations(directory, reservations)) {
+        return {
+          ok: false,
+          reason: "uncertain",
+          detail: "finished reservation reconciliation could not be persisted"
+        };
+      }
+      const activeOwnerKeys = new Set;
+      for (const taskId of occupiedTaskIds) {
+        activeOwnerKeys.add(reservationOwnerKey({
+          parentSessionId: input.parentSessionId,
+          planTaskId: taskId,
+          callID: ""
+        }));
+      }
+      for (const reservation2 of reservations) {
+        if (reservation2.parentSessionId === input.parentSessionId) {
+          activeOwnerKeys.add(reservationOwnerKey(reservation2));
+        }
+      }
+      for (const record of ownerScan.recordsByCorrelation.values()) {
+        if (record.parentSessionId === input.parentSessionId && isActiveCoderOwner(record)) {
+          activeOwnerKeys.add(reservationOwnerKey({
+            parentSessionId: record.parentSessionId,
+            planTaskId: record.planTaskId,
+            callID: record.callID
+          }));
+        }
+      }
+      const reservationId = buildBackgroundCoderReservationId(input);
+      const existing = reservations.find((reservation2) => reservation2.reservationId === reservationId);
+      if (existing) {
+        return {
+          ok: false,
+          reason: input.planTaskId === null ? "duplicate_call" : "duplicate_task",
+          activeCount: activeOwnerKeys.size,
+          existing
+        };
+      }
+      const incomingOwnerKey = reservationOwnerKey(input);
+      if (input.planTaskId !== null && activeOwnerKeys.has(incomingOwnerKey)) {
+        return {
+          ok: false,
+          reason: "duplicate_task",
+          activeCount: activeOwnerKeys.size
+        };
+      }
+      if (activeOwnerKeys.size >= input.maxConcurrent) {
+        return {
+          ok: false,
+          reason: "capacity",
+          activeCount: activeOwnerKeys.size
+        };
+      }
+      if (reservations.length >= MAX_LIVE_BACKGROUND_CODER_RESERVATIONS) {
+        return {
+          ok: false,
+          reason: "capacity",
+          activeCount: activeOwnerKeys.size,
+          detail: "durable reservation store is at its hard safety cap"
+        };
+      }
+      const now = input.now ?? Date.now();
+      const reservation = {
+        reservationId,
+        parentSessionId: input.parentSessionId,
+        planTaskId: input.planTaskId,
+        callID: input.callID,
+        state: "reserved",
+        correlationId: null,
+        createdAt: now,
+        updatedAt: now
+      };
+      if (!await writeBackgroundCoderReservations(directory, [
+        ...reservations,
+        reservation
+      ])) {
+        return {
+          ok: false,
+          reason: "uncertain",
+          detail: "durable reservation claim could not be persisted"
+        };
+      }
+      return {
+        ok: true,
+        reservation,
+        activeCount: activeOwnerKeys.size + 1
+      };
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "uncertain",
+      detail: `background coder reservation lock failed: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+async function bindBackgroundCoderReservation(directory, input) {
+  if (!validateReservationIdentity(input) || !input.reservationId || !input.correlationId || input.correlationId.length > 256 || input.correlationId.trim() !== input.correlationId || input.reservationId !== buildBackgroundCoderReservationId(input)) {
+    return null;
+  }
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_CODER_RESERVATIONS_FILE, STORE_LOCK_AGENT, RESERVATION_LOCK_TASK, async () => {
+      const scan = scanBackgroundCoderReservationsForAdmission(directory);
+      if (scan.status === "uncertain")
+        return null;
+      const index = scan.reservations.findIndex((reservation) => reservation.reservationId === input.reservationId);
+      if (index < 0)
+        return null;
+      const current = scan.reservations[index];
+      if (current.parentSessionId !== input.parentSessionId || current.planTaskId !== input.planTaskId || current.callID !== input.callID) {
+        return null;
+      }
+      if (current.state === "bound") {
+        return current.correlationId === input.correlationId ? current : null;
+      }
+      const next = {
+        ...current,
+        state: "bound",
+        correlationId: input.correlationId,
+        updatedAt: input.now ?? Date.now()
+      };
+      const reservations = [...scan.reservations];
+      reservations[index] = next;
+      return await writeBackgroundCoderReservations(directory, reservations) ? next : null;
+    });
+  } catch {
+    return null;
+  }
+}
+async function releaseBackgroundCoderReservation(directory, input) {
+  if (!validateReservationIdentity(input) || !input.reservationId || input.reservationId !== buildBackgroundCoderReservationId(input) || input.correlationId !== null && (input.correlationId.length === 0 || input.correlationId.length > 256 || input.correlationId.trim() !== input.correlationId)) {
+    return false;
+  }
+  try {
+    return await withEvidenceLock(directory, BACKGROUND_CODER_RESERVATIONS_FILE, STORE_LOCK_AGENT, RESERVATION_LOCK_TASK, async () => {
+      const scan = scanBackgroundCoderReservationsForAdmission(directory);
+      if (scan.status === "uncertain")
+        return false;
+      const index = scan.reservations.findIndex((reservation) => reservation.reservationId === input.reservationId);
+      if (index < 0)
+        return false;
+      const current = scan.reservations[index];
+      if (current.parentSessionId !== input.parentSessionId || current.planTaskId !== input.planTaskId || current.callID !== input.callID || current.correlationId !== input.correlationId) {
+        return false;
+      }
+      if (input.reason === "consumed") {
+        if (current.state !== "bound" || !current.correlationId) {
+          return false;
+        }
+        const ownerScan = await scanDurableCoderOwners(directory);
+        if (ownerScan.status === "uncertain")
+          return false;
+        const primary = ownerScan.primaryByCorrelation.get(current.correlationId);
+        if (!primary || primary.status !== "consumed" || !exactReservationRecordMatch(current, primary)) {
+          return false;
+        }
+      }
+      const reservations = scan.reservations.filter((_, reservationIndex) => reservationIndex !== index);
+      return writeBackgroundCoderReservations(directory, reservations);
+    });
+  } catch {
+    return false;
+  }
+}
+
+export { BACKGROUND_DELEGATIONS_FILE, BACKGROUND_DELEGATION_FALLBACK_DIR, BACKGROUND_CODER_RESERVATIONS_FILE, MAX_LIVE_BACKGROUND_FALLBACKS, MAX_LIVE_BACKGROUND_CODER_RESERVATIONS, MAX_BACKGROUND_OBSERVED_FILES, MAX_BACKGROUND_ADVISORY_CHARS, BACKGROUND_INGESTION_LEASE_MS, readDelegations, scanDelegationsForRecovery, findByCorrelationId, recordPendingDelegation, buildPromptSnapshot, appendDelegationTransition, buildBackgroundCompletionEventId, claimTerminalResult, claimCoderSettlement, normalizeBackgroundObservedFiles, updateCoderSettlement, claimDelegationIngestion, recordDelegationIngestionResult, putPendingBackgroundAdvisory, preparePendingBackgroundAdvisories, acknowledgeObservedBackgroundAdvisories, releasePreparedBackgroundAdvisories, findByBatchId, findOpenAsyncLaneBatches, sweepStaleDelegations, readDelegationFallback, listDelegationFallbacks, scanDelegationFallbacksForRecovery, writeDelegationFallback, removeDelegationFallback, findDelegationForCompletion, promoteDelegationFallback, buildBackgroundCoderReservationId, scanBackgroundCoderReservationsForAdmission, reserveBackgroundCoderSlot, bindBackgroundCoderReservation, releaseBackgroundCoderReservation };