velocious 1.0.661 → 1.0.663

package/README.md

@@ -34,6 +34,7 @@
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
 * Rails-style application process initializer teardown with immutable process identity, reverse idempotent shutdown, and explicit HTTP/background-job ownership (see [docs/application-process-lifecycle.md](docs/application-process-lifecycle.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
+* Explicit database-free in-process HTTP applications with optional request and buffered-response byte limits (see [docs/http-server.md](docs/http-server.md#database-free-applications))
 * Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
 * Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events, authorized database-scoped dashboard counts, and an opt-in release-scoped main/worker generation protocol with acknowledged activation, asynchronous retirement, and retired-main recovery. Production compliance additionally requires downstream supervisor retention/activation ordering and release pins (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
@@ -2613,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
@@ -2907,6 +2908,16 @@ When the server runs in the `development` environment, Velocious watches applica
 
 Starting the HTTP server creates `tmp/server.lock` under the configured application directory before Beacon, workers, or the TCP listener start. A second server for the same app fails fast with the lock owner details instead of partially starting. Normal shutdown removes the lock; stale locks with a dead local PID are reclaimed automatically, while locks from another host or unreadable metadata should be removed manually only after confirming no server is running. See [docs/http-server.md](docs/http-server.md#server-lock).
 
+Set `database: false` for an explicitly database-free application; its HTTP and
+initializer lifecycle remains intact without creating a default pool or an
+implicit route connection checkout. Optional
+`httpServer.maxRequestBodyBytes` and
+`httpServer.maxBufferedResponseBodyBytes` positive byte limits reject oversized
+request bodies with a connection-closing `413` and oversized buffered responses
+with a reported, empty `500`. Both remain unbounded when omitted, and streamed
+`sendFile` responses are unaffected. The request limit is enforced while
+unframed multipart bodies accumulate. See [docs/http-server.md](docs/http-server.md#database-free-applications).
+
 Buffered string and `Uint8Array` responses are compressed with Brotli (`br`) or gzip by default whenever request negotiation and response eligibility allow — no opt-in is required. Disable compression globally with `httpServer.compression: false` or `httpServer.compression: {enabled: false}`, and tune it with `threshold`/`brotliQuality`/`gzipLevel` overrides. Negotiation honors `Accept-Encoding` q-values, wildcards, and identity semantics (empty `406` when no acceptable representation exists), combines repeated `Accept-Encoding` header fields in wire order, and advertises a framework-owned `Vary: Accept-Encoding` on every framework-selected representation (transformed, identity, `406`, and file) so caches key on the field. Streamed `sendFile` responses are never buffered or re-encoded: they are sent identity, so when the client forbids identity the server answers with the same empty `406` without opening or streaming the file. Transformation also skips already-encoded or `no-transform` responses, server-sent events, partial/range responses, bodyless statuses, and non-allowlisted content types. Transformation is additionally excluded automatically for credentialed traffic and validator-carrying responses — requests with `Authorization`/`Cookie` and responses with `Set-Cookie`, `ETag`, `Digest`, or `Content-Digest` are never compressed (compression-oracle protection, and validators stay application-owned). Controllers opt out per response with `response.disableCompression()`, and HEAD requests compute GET-equivalent representation headers without emitting a body. See [docs/http-server.md](docs/http-server.md#response-compression).
 
 # Authorization (CanCan-style)

package/build/application.js

@@ -66,7 +66,7 @@ export default class VelociousApplication {
 
     this.configuration.setRoutes(routes)
 
-    if (!this.configuration.isDatabasePoolInitialized()) {
+    if (this.configuration.database !== false && !this.configuration.isDatabasePoolInitialized()) {
       await this.configuration.initializeDatabasePool()
     }
 

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}) {