velocious 1.0.662 → 1.0.663

package/README.md

@@ -2614,7 +2614,7 @@ actual state sources must still agree.
 
 `maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores; select it with `executionMode: "forked"`.
 
-New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. If an initialized child exits unexpectedly, the worker immediately advertises the freed capacity while failure reports retry; the replacement is spawned lazily by the next dispatch, and a pre-startup crash does not trigger a respawn loop. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
+New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. If an initialized child exits unexpectedly, the worker immediately advertises the freed capacity while failure reports retry; the replacement is spawned lazily by the next dispatch, and a pre-startup crash does not trigger a respawn loop. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. Pooled jobs also persist acceptance evidence (`child_received_at_ms`, `child_started_at_ms`, `child_instance_id`, `child_pid`) so a handed-off job can be told apart from one whose runner never picked it up. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
 
 Cold pooled jobs share one atomic model-bootstrap phase. If that phase fails, all
 waiting jobs receive the failure; a later job in the surviving child cannot run

package/build/background-jobs/adapter.js

@@ -129,6 +129,15 @@ export default class BackgroundJobsAdapter {
    */
   async markCompleted(_args) { throw new Error("BackgroundJobsAdapter#markCompleted is not implemented") }
 
+  /**
+   * Records pooled-child acceptance evidence (received/started timestamps plus
+   * runner identity) for a handed-off job, fenced by its active handoff lease.
+   * Only the fields supplied are written.
+   * @param {{jobId: string, handoffId?: string, workerId?: string, handedOffAtMs?: number, receivedAtMs?: number, startedAtMs?: number, childInstanceId?: string, childPid?: number}} _args - Acceptance report.
+   * @returns {Promise<boolean>} - Whether the fenced report was accepted.
+   */
+  async markChildAccepted(_args) { throw new Error("BackgroundJobsAdapter#markChildAccepted is not implemented") }
+
   /**
    * Returns a handed-off job to its schedule.
    * @param {{jobId: string, delayMs: number, handoffId?: string, workerId?: string, handedOffAtMs?: number}} _args - Reschedule report.

package/build/background-jobs/job-runner.js

@@ -82,10 +82,11 @@ function runnerProcessTitle(JobClass, payload) {
  * @param {object} [options] - Runner options.
  * @param {boolean} [options.closeConnections] - Whether to gracefully close framework connections after the job.
  * @param {boolean} [options.manageProcessTitle] - Whether to set the per-job process title and restore it afterwards. Off for concurrent pooled runners, where interleaved snapshot/restore of the single process-wide `process.title` would corrupt it; the pooled child owns an aggregate title instead.
+ * @param {() => void} [options.onPerformStart] - Observation hook fired once, immediately before perform runs (with its connection acquired). Pooled runners use it to report that the job actually started. Must not throw into the job.
  * @param {string} [options.processType] - Generic application process type.
  * @returns {Promise<"completed" | "rescheduled">} - Acknowledged outcome.
  */
-export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, processType = "background-jobs-runner"} = {}) {
+export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, onPerformStart, processType = "background-jobs-runner"} = {}) {
   const configuration = await configurationResolver()
   configuration.setCurrent()
   await configuration.initialize({type: processType})
@@ -119,6 +120,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
     try {
       await runWithBackgroundJobPayload(payload, async () => {
         await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
+          if (onPerformStart) onPerformStart()
           await perform.apply(jobInstance, jobArgs)
         })
       })

package/build/background-jobs/local-adapter.js

@@ -133,6 +133,13 @@ export default class LocalBackgroundJobsAdapter extends BackgroundJobsAdapter {
    */
   async markCompleted(args) { return await this.store.markCompleted(args) }
 
+  /**
+   * Records pooled-child acceptance evidence for a local handoff.
+   * @param {{jobId: string, handoffId?: string, receivedAtMs?: number, startedAtMs?: number, childInstanceId?: string, childPid?: number}} args - Acceptance report.
+   * @returns {Promise<boolean>} - Whether accepted.
+   */
+  async markChildAccepted(args) { return await this.store.markChildAccepted(args) }
+
   /**
    * Acknowledges an explicit local reschedule.
    * @param {{jobId: string, delayMs: number, handoffId?: string}} args - Reschedule report.

package/build/background-jobs/local-store.js

@@ -49,7 +49,11 @@ const EXPECTED_JOB_COLUMNS = [
   "failed_at_ms",
   "last_error",
   "concurrency_key",
-  "max_concurrency"
+  "max_concurrency",
+  "child_received_at_ms",
+  "child_started_at_ms",
+  "child_instance_id",
+  "child_pid"
 ]
 const EXPECTED_CONCURRENCY_COLUMNS = ["concurrency_key", "max_concurrency", "active_count"]
 /** @type {WeakMap<import("../configuration.js").default, Map<string, Promise<void>>>} */
@@ -202,6 +206,7 @@ export default class LocalBackgroundJobsStore {
       await db.createTable(this._jobsTableData())
       changed = true
     } else {
+      if (await this._ensureJobColumns(db)) changed = true
       await this._assertColumns(db, LOCAL_BACKGROUND_JOBS_TABLE, EXPECTED_JOB_COLUMNS)
     }
 
@@ -232,6 +237,45 @@ export default class LocalBackgroundJobsStore {
     return changed
   }
 
+  /**
+   * Idempotently adds columns from the current jobs table definition that an
+   * existing local table is missing, so an upgraded framework finds a
+   * compatible schema instead of failing the column assertion.
+   * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+   * @returns {Promise<boolean>} - Whether a column was added.
+   */
+  async _ensureJobColumns(db) {
+    db.clearSchemaCache()
+    const table = await db.getTableByNameOrFail(LOCAL_BACKGROUND_JOBS_TABLE)
+    const tableData = new TableData(LOCAL_BACKGROUND_JOBS_TABLE)
+    let added = false
+
+    for (const column of this._jobsTableData().getColumns()) {
+      if (await table.getColumnByName(column.getName())) continue
+      if (column.getPrimaryKey()) continue
+
+      const columnArgs = /** @type {{null: boolean, maxLength?: number}} */ ({null: column.getNull() !== false})
+      const maxLength = column.getMaxLength()
+
+      if (typeof maxLength === "number") columnArgs.maxLength = maxLength
+
+      const type = column.getType()
+      if (type === "string") tableData.string(column.getName(), columnArgs)
+      else if (type === "text") tableData.text(column.getName(), columnArgs)
+      else if (type === "bigint") tableData.bigint(column.getName(), columnArgs)
+      else if (type === "integer") tableData.integer(column.getName(), columnArgs)
+      else if (type === "boolean") tableData.boolean(column.getName(), columnArgs)
+      else continue
+      added = true
+    }
+
+    if (!added) return false
+
+    for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+    db.clearSchemaCache()
+    return true
+  }
+
   /**
    * Builds the migration ledger table definition.
    * @returns {TableData} - Migration ledger table.
@@ -272,6 +316,10 @@ export default class LocalBackgroundJobsStore {
     table.text("last_error", {null: true})
     table.string("concurrency_key", {null: true})
     table.integer("max_concurrency", {null: true})
+    table.bigint("child_received_at_ms", {null: true})
+    table.bigint("child_started_at_ms", {null: true})
+    table.string("child_instance_id", {null: true})
+    table.integer("child_pid", {null: true})
     table.addIndex(new TableIndex(["status", "scheduled_at_ms", "created_at_ms", "id"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[0]}))
     table.addIndex(new TableIndex(["queue", "status", "created_at_ms"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[1]}))
     table.addIndex(new TableIndex(["args_digest"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[2]}))
@@ -708,7 +756,7 @@ export default class LocalBackgroundJobsStore {
       const handedOffAtMs = this.clock.now()
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {id: jobId, status: "queued"},
-        data: {handed_off_at_ms: handedOffAtMs, handoff_id: handoffId, status: "handed_off", worker_id: workerId || "local"},
+        data: {...this._clearedChildAcceptanceData(), handed_off_at_ms: handedOffAtMs, handoff_id: handoffId, status: "handed_off", worker_id: workerId || "local"},
         tableName: LOCAL_BACKGROUND_JOBS_TABLE
       })
 
@@ -763,6 +811,7 @@ export default class LocalBackgroundJobsStore {
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
         data: {
+          ...this._clearedChildAcceptanceData(),
           handed_off_at_ms: null,
           handoff_id: null,
           scheduled_at_ms: this.clock.now(),
@@ -802,6 +851,43 @@ export default class LocalBackgroundJobsStore {
     }))
   }
 
+  /**
+   * Records pooled-child acceptance evidence for an active handoff. Only the
+   * fields supplied are written, fenced by the exact active handoff lease.
+   * @param {object} args - Acceptance report.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @returns {Promise<boolean>} - Whether the lease won.
+   */
+  async markChildAccepted({jobId, handoffId, receivedAtMs, startedAtMs, childInstanceId, childPid}) {
+    await this.ensureReady()
+
+    return await this._withDb(async (connection) => await this._mutate(connection, async (db) => {
+      const job = await this._getJob(db, jobId)
+
+      if (!this._acceptsHandoff(job, handoffId)) return false
+
+      const data = {}
+      if (typeof receivedAtMs === "number") data.child_received_at_ms = receivedAtMs
+      if (typeof startedAtMs === "number") data.child_started_at_ms = startedAtMs
+      if (typeof childInstanceId === "string") data.child_instance_id = childInstanceId
+      if (typeof childPid === "number") data.child_pid = childPid
+      if (Object.keys(data).length === 0) return false
+
+      const affectedRows = await this._updateAffectedRows(db, {
+        conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
+        data,
+        tableName: LOCAL_BACKGROUND_JOBS_TABLE
+      })
+
+      return affectedRows === 1
+    }))
+  }
+
   /**
    * Applies a fenced reschedule without consuming an attempt.
    * @param {{jobId: string, handoffId?: string, delayMs: number}} args - Reschedule report.
@@ -819,6 +905,7 @@ export default class LocalBackgroundJobsStore {
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
         data: {
+          ...this._clearedChildAcceptanceData(),
           handed_off_at_ms: null,
           handoff_id: null,
           scheduled_at_ms: rescheduledBackgroundJobAtMs(delayMs, this.clock.now()),
@@ -917,7 +1004,9 @@ export default class LocalBackgroundJobsStore {
     }
 
     if (willRetry) {
-      Object.assign(data, {scheduled_at_ms: nowMs + retryDelayMs(attempts)})
+      // A retry starts a fresh handoff with a possibly different runner, so the
+      // previous child's acceptance evidence must not leak into the next attempt.
+      Object.assign(data, {scheduled_at_ms: nowMs + retryDelayMs(attempts), ...this._clearedChildAcceptanceData()})
     } else {
       Object.assign(data, {failed_at_ms: nowMs})
     }
@@ -934,6 +1023,7 @@ export default class LocalBackgroundJobsStore {
 
     return {
       ...job,
+      ...(willRetry ? this._clearedChildAcceptanceRow() : {}),
       attempts,
       failedAtMs: willRetry ? job.failedAtMs : nowMs,
       handedOffAtMs: null,
@@ -945,6 +1035,22 @@ export default class LocalBackgroundJobsStore {
     }
   }
 
+  /**
+   * Returns the database data that clears pooled-child acceptance evidence.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Cleared acceptance columns.
+   */
+  _clearedChildAcceptanceData() {
+    return {child_instance_id: null, child_pid: null, child_received_at_ms: null, child_started_at_ms: null}
+  }
+
+  /**
+   * Returns the row-shape counterpart of the cleared acceptance columns.
+   * @returns {Pick<import("./types.js").BackgroundJobRow, "childInstanceId" | "childPid" | "childReceivedAtMs" | "childStartedAtMs">} - Cleared acceptance fields.
+   */
+  _clearedChildAcceptanceRow() {
+    return {childInstanceId: null, childPid: null, childReceivedAtMs: null, childStartedAtMs: null}
+  }
+
   /**
    * Ensures that a durable concurrency counter exists with the required cap.
    * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
@@ -1106,6 +1212,10 @@ export default class LocalBackgroundJobsStore {
     return {
       args: parsedArgs,
       attempts: this._numberOrNull(row.attempts),
+      childInstanceId: row.child_instance_id === null || row.child_instance_id === undefined ? null : String(row.child_instance_id),
+      childPid: this._numberOrNull(row.child_pid),
+      childReceivedAtMs: this._numberOrNull(row.child_received_at_ms),
+      childStartedAtMs: this._numberOrNull(row.child_started_at_ms),
       completedAtMs: this._numberOrNull(row.completed_at_ms),
       concurrencyKey: row.concurrency_key === null || row.concurrency_key === undefined ? null : String(row.concurrency_key),
       createdAtMs: this._numberOrNull(row.created_at_ms),

package/build/background-jobs/main.js

@@ -1219,6 +1219,11 @@ export default class BackgroundJobsMain {
       }
       return
     }
+    if (message?.type === "job-accepted") {
+      await this._handleJobAccepted({jsonSocket, message})
+      return
+    }
+
     if (message?.type === "job-complete") {
       await this._handleJobComplete({jsonSocket, message})
       return
@@ -1234,6 +1239,35 @@ export default class BackgroundJobsMain {
     }
   }
 
+  /**
+   * Persists pooled-child acceptance evidence for an active handoff. The
+   * report is diagnostic: a stale lease (job already reclaimed or terminal)
+   * answers the same `job-updated` acknowledgement as an accepted report, and
+   * only a store failure answers `job-update-error` so the worker can retry.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobAcceptedMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleJobAccepted({jsonSocket, message}) {
+    try {
+      await this.store.markChildAccepted({
+        childInstanceId: message.childInstanceId,
+        childPid: message.childPid,
+        handedOffAtMs: message.handedOffAtMs,
+        handoffId: message.handoffId,
+        jobId: message.jobId,
+        receivedAtMs: message.receivedAtMs,
+        startedAtMs: message.startedAtMs,
+        workerId: message.workerId
+      })
+      jsonSocket.send({type: "job-updated", jobId: message.jobId})
+    } catch (error) {
+      this._reportJobUpdateFailure({error, jobId: message.jobId, stage: "background-job-accepted"})
+      jsonSocket.send({type: "job-update-error", jobId: message.jobId, error: "Failed to update job"})
+    }
+  }
+
   /**
    * Requires the complete durable lease identity before a generation-mode
    * reporter can mutate a job. Legacy reporters keep their permissive protocol.
@@ -1241,7 +1275,7 @@ export default class BackgroundJobsMain {
    * @returns {boolean} - Whether the report lacks its exact generation lease.
    */
   _generationReportIsInvalid(message) {
-    if (message?.type !== "job-complete" && message?.type !== "job-failed" && message?.type !== "job-reschedule") return false
+    if (message?.type !== "job-accepted" && message?.type !== "job-complete" && message?.type !== "job-failed" && message?.type !== "job-reschedule") return false
     const generationId = this.generationId
     if (!generationId) return false
 

package/build/background-jobs/pooled-runner-child.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import { randomUUID } from "node:crypto"
 import runJobPayload, { BackgroundJobPerformedFailure } from "./job-runner.js"
 import { closeRunnerConnections, closeRunnerFrameworkConnections, currentConfigurationOrNull } from "./runner-graceful-shutdown.js"
 import setRunnerProcessTitle from "./runner-process-title.js"
@@ -7,6 +8,8 @@ import PooledRunnerBrokerIdentity from "./pooled-runner-broker-identity.js"
 import { runWithSharedTransactionBrokerConfig } from "../testing/shared-transaction-proxy-driver.js"
 
 const BASE_PROCESS_TITLE = "velocious background-jobs-runner"
+/** Stable identity of this pooled child process for the life of the process. */
+const childInstanceId = randomUUID()
 
 setRunnerProcessTitle()
 
@@ -57,6 +60,39 @@ function updateProcessTitle() {
   process.title = count > 0 ? `${BASE_PROCESS_TITLE}: ${count} ${count === 1 ? "job" : "jobs"}` : BASE_PROCESS_TITLE
 }
 
+/**
+ * Reports one acceptance observation (job received / perform started) to the
+ * worker over IPC. The message carries the job's exact handoff lease so the
+ * worker can persist it fenced without any other lookup. Send failures are
+ * swallowed: a dead IPC channel is terminal for this child (the disconnect
+ * handler owns shutdown), and losing acceptance evidence must never fail the
+ * job itself.
+ * @param {"job-received" | "job-started"} type - Observation kind.
+ * @param {import("./types.js").BackgroundJobPayload & {id: string}} payload - Job payload carrying the handoff lease.
+ * @param {number} observedAtMs - Epoch ms of the observation.
+ * @returns {void}
+ */
+function sendChildAcceptance(type, payload, observedAtMs) {
+  if (!process.send) return
+
+  const message = {
+    childInstanceId,
+    childPid: process.pid,
+    handedOffAtMs: payload.handedOffAtMs,
+    handoffId: payload.handoffId,
+    jobId: payload.id,
+    type,
+    workerId: payload.workerId,
+    ...(type === "job-received" ? {receivedAtMs: observedAtMs} : {startedAtMs: observedAtMs})
+  }
+
+  try {
+    process.send(message)
+  } catch {
+    // The IPC channel is already gone; the disconnect handler owns shutdown.
+  }
+}
+
 /**
  * Checks whether an IPC value is a runnable pooled job message.
  * @param {ReturnType<typeof JSON.parse>} message - IPC message.
@@ -114,6 +150,7 @@ async function runJob(payload, sharedTransactionBroker) {
         return await runJobPayload(payload, {
           closeConnections: false,
           manageProcessTitle: false,
+          onPerformStart: () => sendChildAcceptance("job-started", payload, Date.now()),
           processType: "background-jobs-pooled-runner"
         })
       })
@@ -143,6 +180,7 @@ function handleMessage(message) {
 
   runningJobIds.add(message.payload.id)
   updateProcessTitle()
+  sendChildAcceptance("job-received", message.payload, Date.now())
   void runJob(message.payload, message.sharedTransactionBroker || {expected: false})
 }
 

package/build/background-jobs/status-reporter.js

@@ -92,6 +92,102 @@ export default class BackgroundJobsStatusReporter {
     })
   }
 
+  /**
+   * Runs report child accepted.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {string} [args.workerId] - Worker id.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @returns {Promise<void>} - Resolves when reported.
+   */
+  async reportChildAccepted({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid}) {
+    const config = this.configuration.getBackgroundJobsConfig()
+    const host = this.host || config.host
+    const port = typeof this.port === "number" ? this.port : config.port
+    const {generationId} = this.configuration.resolveBackgroundJobsGenerationConfig({
+      generationId: this.explicitGenerationId,
+      sourceName: "BackgroundJobsStatusReporter"
+    })
+
+    await timeout({timeout: this.attemptTimeoutMs}, async ({control}) => {
+      const request = new BackgroundJobsSocketRequest({host, port, role: "reporter", generationHandshakeTimeoutMs: this.generationHandshakeTimeoutMs, generationId})
+
+      this._lastRequest = request
+
+      await request.run({
+        signal: control.signal,
+        onConnect: (jsonSocket) => {
+          jsonSocket.send({
+            type: "job-accepted",
+            jobId,
+            handoffId,
+            workerId,
+            handedOffAtMs,
+            receivedAtMs,
+            startedAtMs,
+            childInstanceId,
+            childPid
+          })
+        },
+        onMessage: ({message, resolve, reject}) => {
+          if (message?.type === "job-updated" && message.jobId === jobId) {
+            resolve(undefined)
+            return
+          }
+
+          if (message?.type === "job-update-error" && message.jobId === jobId) {
+            reject(new BackgroundJobUpdateError(message.error || "Job update failed"))
+          }
+        }
+      })
+    })
+  }
+
+  /**
+   * Runs report child accepted with retry. Acceptance evidence is diagnostic
+   * rather than terminal, so a transient main/DB failure retries only until
+   * `maxDurationMs` elapses and then gives up instead of stranding the report.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {string} [args.workerId] - Worker id.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @param {number} args.maxDurationMs - Max duration for retries.
+   * @returns {Promise<void>} - Resolves when reported or the budget elapses.
+   */
+  async reportChildAcceptedWithRetry({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid, maxDurationMs}) {
+    let attempt = 0
+    const startTime = Date.now()
+
+    while (true) {
+      try {
+        await this.reportChildAccepted({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid})
+        return
+      } catch (error) {
+        attempt += 1
+        const delaySeconds = Math.min(30, 0.5 * attempt)
+
+        this.logger.debug(() => ["Background job child-acceptance report failed, retrying", error])
+
+        if (Date.now() - startTime >= maxDurationMs) {
+          this.logger.warn(() => ["Background job child-acceptance report timed out, giving up", error])
+          throw error
+        }
+
+        await wait(delaySeconds)
+      }
+    }
+  }
+
   /**
    * Runs report with retry.
    * @param {object} args - Options.
@@ -104,7 +200,7 @@ export default class BackgroundJobsStatusReporter {
    * @param {string} [args.workerId] - Worker id.
    * @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
    * @param {number} [args.maxDurationMs] - Max duration for retries.
-   * @param {boolean} [args.retryPersistErrors] - Retry a `BackgroundJobUpdateError` (main's `job-update-error`, i.e. a transient DB failure while persisting the terminal status) instead of throwing immediately. Off by default so short-lived forked/spawned runners keep failing loudly and exit non-zero to be reclaimed; on for the long-lived worker, which cannot exit-to-reclaim and would otherwise strand the job in `handed_off`.
+   * @param {boolean} [args.retryPersistErrors] - Retry a `BackgroundJobUpdateError` (main's `job-update-error`, i.e. a transient DB failure while persisting the terminal status) instead of throwing immediately. Off by default so short-lived forked/spawned runners keep failing loudly and exit non-zero to be reclaimed; on for the long-lived worker, which cannot exit to trigger orphan reclaim and would otherwise drop the completion and strand the row in `handed_off`.
    * @returns {Promise<void>} - Resolves when reported.
    */
   async reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure, maxDurationMs, retryPersistErrors = false}) {