@deepblend/dsh-blender-provider-local 0.2.4 → 0.2.6

package/lib/index.js

@@ -21,6 +21,7 @@
 
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import net from 'node:net'
 import { readFile } from 'node:fs/promises'
 import { delimiter, isAbsolute, join, resolve, sep } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -142,6 +143,30 @@ export const ProviderConfig = z.object({
   capabilitiesCacheMs: z.number().default(60_000),
   /** Retain per-invocation working directories for post-mortem inspection. */
   keepWorkingDirectory: z.boolean().default(false),
+  /**
+   * Actions served from a KEPT Blender process instead of one process each (SPEC §20 M6).
+   *
+   * EMPTY BY DEFAULT, AND THAT IS THE HONEST DEFAULT — MEASURED, not cautious. Turning it on for
+   * `get_capabilities` and `compile_scene` made three acceptance suites fail, and they were right:
+   * a kept session has a NARROWER CONTRACT than a batch invocation. It does not capture per-request
+   * stdout (the capture cap and the flood test have nothing to read), a per-request deadline does not
+   * kill the process (the deadline test found a Blender still in the process table), and it holds its
+   * working directory for as long as it lives (the M0 probe found temp directories left behind).
+   *
+   * None of that is a bug in the session; it is a different shape with different promises. But a
+   * default that silently swaps one set of promises for another is exactly the kind of change this
+   * repository's suites exist to catch, so the fast path is OPT IN: an operator who wants it names the
+   * actions, and the actions that are safe for it are the pure, short ones — `get_capabilities` and
+   * `compile_scene`. MEASURED with it on: three operations cost 832 ms instead of 2594 ms, in one
+   * process instead of three (`milestone-status.md` §212.6).
+   *
+   * The RENDERS are not safe for it in any configuration: cancelling one must kill exactly that
+   * render, and the only way this provider can do that is to end the process — which, on an ATTACHED
+   * Blender, is the user's own session.
+   */
+  sessionActions: z.array(z.string()).default([]),
+  /** How long a kept session may sit idle before it is closed. */
+  sessionIdleMs: z.number().default(60_000),
 })
 
 /**
@@ -154,6 +179,124 @@ export const ProviderConfig = z.object({
  * @property {string} workingDirectory
  */
 
+/** How long an attached Blender gets to say hello before the attach is called a failure. */
+const ATTACH_READY_MS = 10_000
+
+/**
+ * Connect to a Unix socket, with a deadline.
+ *
+ * The add-on may be starting when the product asks — a user enables it and the product is already
+ * polling — so this retries inside one deadline rather than failing on the first refusal.
+ *
+ * @param {string} socketPath
+ * @param {number} timeoutMs
+ * @returns {Promise<import('node:net').Socket>}
+ */
+async function connect(socketPath, timeoutMs) {
+  const deadline = Date.now() + Math.min(timeoutMs, 10_000)
+  let lastError = null
+  for (;;) {
+    const socket = await new Promise(resolve => {
+      const candidate = net.connect(socketPath)
+      candidate.once('connect', () => resolve(candidate))
+      candidate.once('error', error => {
+        lastError = error
+        candidate.destroy()
+        resolve(null)
+      })
+    })
+    if (socket !== null) return socket
+    if (Date.now() >= deadline) throw lastError ?? new Error('no answer')
+    await new Promise(settle => setTimeout(settle, 250))
+  }
+}
+
+/**
+ * A live Blender, presented as one shape whatever carries the bytes.
+ *
+ * WHY THE SEAM EXISTS. A session can be carried two ways, and both are real: the process this
+ * provider SPAWNS (`--background`, pipes on stdin/stdout) and the Blender a USER is looking at (the
+ * add-on's socket). The conversation — the handshake, the per-request deadline, matching an answer to
+ * its request — is identical, and the only thing that differs is who owns the other end. Writing it
+ * twice would mean two places to fix the next bug in the deadline, and the second one would be the
+ * one nobody runs.
+ *
+ * The subprocess adapter and the socket adapter below are the whole of the difference.
+ */
+class SubprocessTransport {
+  /** @param {object} handle from `ctx.subprocess.spawn` */
+  constructor(handle) {
+    this.handle = handle
+    this.read = handle.stdout
+    this.onExit = callback => handle.done?.then?.(() => callback({}), () => callback({}))
+    this.pid = null
+  }
+
+  write(text) {
+    this.handle.stdin.write(text)
+  }
+
+  end() {
+    try {
+      this.handle.stdin.end()
+    } catch {
+      // Already gone; the exit callback is what decides.
+    }
+  }
+
+  /** Wait for the process to be gone, bounded. */
+  async settle(graceMs) {
+    try {
+      await this.handle.waitForExit?.(graceMs)
+    } catch {
+      // A process that had to be terminated is still a settled one.
+    }
+  }
+}
+
+class SocketTransport {
+  /**
+   * @param {import('node:net').Socket} socket
+   * @param {{ pid?: number|null }} [info]
+   */
+  constructor(socket, info = {}) {
+    this.socket = socket
+    this.read = socket
+    // The pid is the ATTACHED Blender's own, from its handshake — never this process's. A product that
+    // reported its own pid here would make "which Blender answered" unanswerable, which is the one
+    // question an attach exists to answer.
+    this.pid = info.pid ?? null
+    this.exitCallbacks = []
+    socket.on('close', () => {
+      for (const callback of this.exitCallbacks) callback({})
+    })
+    socket.on('error', () => {
+      // An error closes the socket, and the close handler reports it. Swallowing it here keeps a
+      // broken pipe from becoming an unhandled 'error' event, which would take the host down.
+    })
+  }
+
+  onExit(callback) {
+    this.exitCallbacks.push(callback)
+  }
+
+  write(text) {
+    this.socket.write(text)
+  }
+
+  end() {
+    try {
+      this.socket.end()
+    } catch {
+      // Already closed.
+    }
+  }
+
+  async settle() {
+    this.socket.destroy()
+  }
+}
+
 /**
  * One live Blender process, serving requests until it is closed (SPEC §20 M6).
  *
@@ -170,10 +313,11 @@ export const ProviderConfig = z.object({
  */
 class BlenderSession {
   /**
-   * @param {{ handle: object, directory: string, jobId: string, timeoutMs: number, onClose: () => void }} input
+   * @param {{ transport: SubprocessTransport|SocketTransport, directory: string|null, jobId: string, timeoutMs: number, onClose: () => void }} input
    */
   constructor(input) {
-    this.handle = input.handle
+    this.transport = input.transport
+    this.handle = input.transport.handle ?? null
     this.directory = input.directory
     this.jobId = input.jobId
     this.timeoutMs = input.timeoutMs
@@ -182,7 +326,7 @@ class BlenderSession {
     // `done`, `terminate`, `terminateForHostExit`, `waitForExit`. So the pid comes from the process
     // itself, in the `ready` line bootstrap.py opens with — which is better evidence anyway, because
     // it is the pid the script believes it is rather than the one the spawn returned.
-    this.pid = null
+    this.pid = input.transport.pid ?? null
     /** @type {Map<string, {resolve: Function, reject: Function, timer: object}>} */
     this.waiting = new Map()
     this.progress = []
@@ -193,15 +337,42 @@ class BlenderSession {
     this.readyPromise = null
     this.readyResolve = null
     this.readyReject = null
+    this.readySettled = false
     this._read()
   }
 
-  /** Resolve when bootstrap.py has announced itself, reject if the process dies first. */
-  ready() {
+  /**
+   * Resolve when the other end has announced itself — reject if it dies first, or says nothing.
+   *
+   * THE DEADLINE IS THE POINT, and a mutation found it missing: with the handshake removed from the
+   * bridge, `attachSession` connected successfully and then waited FOREVER, because the socket stayed
+   * open and simply never spoke. A hang is worse than either a success or a coded failure — it has no
+   * message, no code, and no end — and this repository's rule is that a failure has to be a branchable
+   * result. The same deadline that bounds a request bounds the opening of the conversation.
+   */
+  ready(timeoutMs = this.timeoutMs) {
     if (this.readyPromise === null) {
       this.readyPromise = new Promise((resolve, reject) => {
-        this.readyResolve = resolve
-        this.readyReject = reject
+        const timer = setTimeout(() => {
+          if (this.readySettled) return
+          this.readySettled = true
+          reject(new BlenderError(
+            BlenderErrorCode.TIMEOUT,
+            `The Blender session (pid ${this.pid ?? 'unknown'}) connected but never announced itself within ${timeoutMs} ms.`,
+            { detail: { pid: this.pid, timeoutMs } },
+          ))
+        }, timeoutMs)
+        if (typeof timer.unref === 'function') timer.unref()
+        this.readyResolve = value => {
+          clearTimeout(timer)
+          this.readySettled = true
+          resolve(value)
+        }
+        this.readyReject = error => {
+          clearTimeout(timer)
+          this.readySettled = true
+          reject(error)
+        }
       })
     }
     return this.readyPromise
@@ -209,7 +380,7 @@ class BlenderSession {
 
   /** Read stdout line by line for the life of the process. */
   _read() {
-    const stream = this.handle?.stdout
+    const stream = this.transport.read
     if (stream === undefined || stream === null) {
       this._fail(new BlenderError(BlenderErrorCode.SPAWN_FAILED, 'the session has no stdout stream to read'))
       return
@@ -229,10 +400,10 @@ class BlenderSession {
       // Bounded: stderr is evidence for a failure, not a log to keep.
       this.stderr = (this.stderr + chunk.toString('utf8')).slice(-8192)
     })
-    // THE HANDLE'S EXIT SIGNAL IS A PROMISE, NOT AN EVENT (`done`), and it carries nothing — so the
-    // exit code is read from `waitForExit()` where one is needed, and the failure below says what is
-    // knowable: the session ended without answering.
-    this.handle?.done?.then?.(() => this._exited({}), () => this._exited({}))
+    // THE TRANSPORT REPORTS THE END, whatever the end means: for a spawned process the handle's
+    // `done` promise, for a socket its 'close'. Neither carries a code — the failure below says what
+    // is knowable, which is that the session ended without answering.
+    this.transport.onExit(info => this._exited(info))
   }
 
   _line(line) {
@@ -287,7 +458,7 @@ class BlenderSession {
   /**
    * Run one action in the live process.
    *
-   * @param {{ action: string, payload?: object, jobId?: string }} request
+   * @param {{ action: string, payload?: object, args?: string[], jobId?: string }} request
    * @param {{ signal?: AbortSignal }} [options]
    * @returns {Promise<object>} the envelope bootstrap.py built for it.
    */
@@ -304,6 +475,11 @@ class BlenderSession {
       jobId,
       action: request.action,
       ...(request.payload !== undefined ? { payload: request.payload } : {}),
+      // PER-REQUEST ARGUMENTS. A session's argv is fixed when the process starts, and the actions that
+      // matter need flags (`--scene-spec`, `--output`, …), so the request carries its own and
+      // bootstrap.py parses them with the same parser the process used. MEASURED: without this, every
+      // real action failed inside a session with "requires --scene-spec".
+      ...(Array.isArray(request.args) ? { args: request.args } : {}),
     }
 
     const answered = new Promise((resolve, reject) => {
@@ -331,7 +507,7 @@ class BlenderSession {
       }
     })
 
-    this.handle.stdin.write(`${JSON.stringify(document)}\n`)
+    this.transport.write(`${JSON.stringify(document)}\n`)
     return answered
   }
 
@@ -339,17 +515,12 @@ class BlenderSession {
   async close() {
     if (this.closed) return
     try {
-      this.handle.stdin.write(`${JSON.stringify({ action: 'shutdown' })}\n`)
-      this.handle.stdin.end()
-    } catch {
-      // The process may already be gone; the wait below is what decides.
-    }
-    try {
-      // `waitForExit` is the handle's own way to wait, and it takes a deadline in milliseconds.
-      await this.handle.waitForExit?.(TERMINATE_GRACE_MS)
+      this.transport.write(`${JSON.stringify({ action: 'shutdown' })}\n`)
+      this.transport.end()
     } catch {
-      // A process that had to be terminated is still a closed session.
+      // The other end may already be gone; the settle below is what decides.
     }
+    await this.transport.settle(TERMINATE_GRACE_MS)
     this.closed = true
     this._fail(new BlenderError(
       BlenderErrorCode.ABORTED,
@@ -376,6 +547,10 @@ export default class LocalBlenderRuntime extends Service {
   /** @type {Map<string, import('@deepblend/dsh-blender-contracts').BlenderCapabilities>} */
   _capabilitiesCache = new Map()
 
+  /** The kept Blender for `sessionActions`, and the timer that closes it when it goes quiet. */
+  _session = null
+  _sessionTimer = null
+
   /**
    * @param {import('@deepseek-ai/cordis').Context} ctx
    * @param {import('z').infer<typeof ProviderConfig>} config - validated by schemastery before construction.
@@ -389,6 +564,11 @@ export default class LocalBlenderRuntime extends Service {
     this.bootstrapPath = this._resolveBootstrapPath(config.bootstrapPath)
     /** Resolved once: the host must be configured with the same value. */
     this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot)
+    // A KEPT SESSION IS A PROCESS THIS ROW OWNS, so it is disposed with the row rather than left for
+    // the host's exit path to find: a plugin that is unloaded must not leave a Blender behind.
+    ctx.effect(() => () => {
+      this.closeSession().catch(() => {})
+    }, 'deepblend kept session teardown')
   }
 
   /**
@@ -692,7 +872,7 @@ export default class LocalBlenderRuntime extends Service {
     })
 
     const session = new BlenderSession({
-      handle,
+      transport: new SubprocessTransport(handle),
       directory,
       jobId,
       timeoutMs: this.config.timeoutMs,
@@ -702,6 +882,103 @@ export default class LocalBlenderRuntime extends Service {
     return session
   }
 
+  /**
+   * Attach to a Blender that is ALREADY RUNNING — the user's own, with the add-on (SPEC §20 M6).
+   *
+   * THE OTHER HALF OF THE LIVE BRIDGE. `openSession()` spawns a Blender nobody can see; this one talks
+   * to the Blender on the user's screen, so the operations happen in the window they are looking at.
+   * The conversation is identical — same protocol, same envelopes, same per-request deadline — because
+   * both go through `BlenderSession`; the only difference is who owns the other end of the bytes.
+   *
+   * The pid in the handshake is the ATTACHED Blender's own, and it is what makes "which Blender
+   * answered this" answerable. A product that reported its own pid here would make that question
+   * unanswerable, which is the one question an attach exists to answer.
+   *
+   * @param {string} socketPath
+   * @param {{ timeoutMs?: number }} [options]
+   * @returns {Promise<{ pid: number|null, run: Function, close: Function }>}
+   */
+  async attachSession(socketPath, options = {}) {
+    if (typeof socketPath !== 'string' || socketPath.length === 0) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        'Attaching needs the socket path the Blender add-on is listening on.',
+      )
+    }
+    if (!existsSync(socketPath)) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `Nothing is listening at ${socketPath}. Enable the DeepBlend bridge add-on in Blender ` +
+          '(View3D > Sidebar > DeepBlend), or start one headless with ' +
+          '`blender --background --python deepblend_bridge.py -- --socket <path>`.',
+        { detail: { socketPath } },
+      )
+    }
+
+    const socket = await connect(socketPath, options.timeoutMs ?? this.config.timeoutMs).catch(cause => {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `The Blender bridge at ${socketPath} could not be reached: ${cause?.message ?? 'unknown failure'}.`,
+        { detail: { socketPath } },
+      )
+    })
+
+    const session = new BlenderSession({
+      transport: new SocketTransport(socket),
+      directory: null,
+      jobId: `attach-${randomUUID()}`,
+      timeoutMs: this.config.timeoutMs,
+      onClose: () => {},
+    })
+    // A SHORTER DEADLINE THAN A SPAWN, and the difference is real rather than a preference: a spawned
+    // Blender legitimately takes a second or two to boot, while an add-on that is already serving
+    // answers the handshake immediately. MEASURED: with the provider's own 180 s timeout, a peer that
+    // connected and said nothing took 180 s to report — long enough that a user would conclude the
+    // product had hung.
+    await session.ready(ATTACH_READY_MS)
+    return session
+  }
+
+  /**
+   * The kept session, opened on first use and closed when it has been idle.
+   *
+   * A SESSION IS NOT A CACHE. It is a Blender process holding a loaded scene, so it is closed on a
+   * timer rather than kept forever: an operator who runs one compile and walks away should not find a
+   * Blender still resident an hour later. The timer is refreshed by use and cleared on disposal.
+   */
+  async _keptSession() {
+    if (this._session !== null && !this._session.closed) return this._session
+    this._session = await this.openSession()
+    return this._session
+  }
+
+  _touchSession() {
+    if (this._sessionTimer !== null) clearTimeout(this._sessionTimer)
+    this._sessionTimer = setTimeout(() => {
+      // NEVER CLOSE UNDER A REQUEST. MEASURED: the first version closed on the timer alone, and a
+      // compile that was still running when the idle window expired was rejected with "closed by its
+      // caller" — the session ended a request that had done nothing wrong. Idle means idle.
+      if (this._session !== null && this._session.waiting.size > 0) {
+        this._touchSession()
+        return
+      }
+      const session = this._session
+      this._session = null
+      this._sessionTimer = null
+      session?.close?.().catch(() => {})
+    }, this.config.sessionIdleMs)
+    if (typeof this._sessionTimer.unref === 'function') this._sessionTimer.unref()
+  }
+
+  /** Close the kept session now, if there is one. */
+  async closeSession() {
+    if (this._sessionTimer !== null) clearTimeout(this._sessionTimer)
+    this._sessionTimer = null
+    const session = this._session
+    this._session = null
+    if (session !== null) await session.close().catch(() => {})
+  }
+
   async runBootstrap(request, options = {}) {
     const action = request?.action
     if (typeof action !== 'string' || action.length === 0) {
@@ -715,6 +992,28 @@ export default class LocalBlenderRuntime extends Service {
       )
     }
 
+    // THE SESSION PATH, for the actions configured to use one. It returns the SAME outcome shape the
+    // batch path returns — a caller must not be able to tell which one served it, or the two paths
+    // would drift into two behaviours with one name.
+    if (this.config.sessionActions.includes(action) && options.session !== false) {
+      const session = await this._keptSession()
+      this._touchSession()
+      const startedAt = Date.now()
+      const envelope = await session.run({
+        action,
+        ...(request.payload !== undefined ? { payload: request.payload } : {}),
+        ...(Array.isArray(options.args) ? { args: options.args } : {}),
+      }, { signal: options.signal })
+      return {
+        envelope,
+        stdout: '',
+        stderr: '',
+        exitCode: envelope.status === 'error' ? 1 : 0,
+        durationMs: Date.now() - startedAt,
+        workingDirectory: session.directory ?? null,
+      }
+    }
+
     const resolvedExecutable = await this.resolveBlenderExecutable({ signal: options.signal })
     if (resolvedExecutable.error !== null || resolvedExecutable.resolved === null) {
       throw resolvedExecutable.error ?? new BlenderError(
@@ -1065,7 +1364,14 @@ export default class LocalBlenderRuntime extends Service {
    * @returns {Promise<{report: object, envelope: object, durationMs: number, stdout: string, stderr: string}>}
    */
   async compileScene(request) {
-    const outputBlend = 'result.blend'
+    // AN ABSOLUTE, PER-REQUEST OUTPUT PATH, and it is what lets the same action run in either
+    // transport. MEASURED: this used to be the relative `'result.blend'`, which was safe only because
+    // the batch path gives every invocation its own working directory — a session has ONE directory
+    // for every request, so two compiles would write the same file and the caller would be handed a
+    // checkpoint that belonged to a different one. Passing the path explicitly removes the dependency
+    // on a working directory that a kept process does not have per request.
+    const { directory: requestDirectory } = this._createWorkingDirectory()
+    const outputBlend = join(requestDirectory, 'result.blend')
     if (typeof request?.sceneSpecPath !== 'string' || request.sceneSpecPath.length === 0) {
       throw new BlenderError(
         BlenderErrorCode.SCENE_SPEC_INVALID,
@@ -1083,10 +1389,18 @@ export default class LocalBlenderRuntime extends Service {
         signal: request.signal,
         args,
         projectRoot: request.projectRoot,
-        onWorkingDirectory: request.onWorkingDirectory,
+        // NOT `onWorkingDirectory` here: the callback has to name the directory that HOLDS the
+        // checkpoint, and that is this method's own (`runBootstrap` would name its invocation
+        // directory, which in a session is a different one). One owner for one path.
       },
     )
 
+    // The caller moves the checkpoint somewhere durable before this directory goes away, which is what
+    // lets a compile failure leave no trace in the project.
+    if (typeof request.onWorkingDirectory === 'function') {
+      await request.onWorkingDirectory({ directory: requestDirectory, envelope: run.envelope, jobId: request.jobId })
+    }
+
     const report = run.envelope.result ?? {}
     return {
       report,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.2.4"
+    "@deepblend/dsh-blender-contracts": "0.2.6"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -429,6 +429,15 @@ def _as_int(value):
         raise ActionError("BLENDER_SCRIPT_ERROR", '"%s" is not an integer' % (value,))
 
 
+# The options a REQUEST may carry, which is the batch path's own list: a session request that names a
+# flag the batch path knows must work, and one it does not must fail the same way.
+KNOWN_SESSION_OPTIONS = (
+    "--request", "--result", "--scene-spec", "--blend", "--output-blend",
+    "--output", "--camera", "--engine", "--width", "--height", "--samples",
+    "--frame", "--profile", "--project-root", "--save-on-failure", "--views",
+    "--frames", "--events", "--proc",
+)
+
 ACTIONS = {
     "get_capabilities": action_get_capabilities,
     "compile_scene": action_compile_scene,
@@ -552,6 +561,27 @@ def _session_dispatch(request, options):
             "detail": {"action": action, "supported": list(SUPPORTED_ACTIONS)},
         }, [], [])
 
+    # PER-REQUEST ARGUMENTS, merged over the process's own.
+    #
+    # MEASURED, and it made sessions useless for the actions that matter: `compile_scene` needs
+    # `--scene-spec`, `render_preview` needs `--output`, and the batch path passes those as extra
+    # argv — but a session's argv is fixed when the process starts, so the first attempt at reusing a
+    # process dropped every one of them and every real action failed with "requires --scene-spec".
+    #
+    # The fix is not to restart the process with new flags (that is the batch path) but to let a
+    # request carry its own, parsed by the SAME parser the process used: one parser, so a flag that
+    # works in batch mode works here, including the failure for an unknown one.
+    options = options
+    if isinstance(request.get("args"), list):
+        extra, unknown = parse_args(["--"] + [str(token) for token in request["args"]], KNOWN_SESSION_OPTIONS)
+        if unknown:
+            return build_envelope(job_id, action, None, {
+                "code": "BLENDER_SCRIPT_ERROR",
+                "message": "unrecognised arguments: %s" % (", ".join(unknown),),
+            }, [], [])
+        options = dict(options)
+        options.update(extra)
+
     eprint("session action=%s job=%s" % (action, job_id))
     # Same claim as the batch path: every request is attributable to this pid, so a session that
     # dies mid-action leaves the same evidence an interrupted render does.

package/python/deepblend_bridge.py

@@ -0,0 +1,306 @@
+"""DeepBlend Studio — the Blender-side bridge (SPEC §20 M6 "Blender Add-on" / "Live Bridge").
+
+WHAT THIS IS
+------------
+One file with two entry points, and that is deliberate:
+
+* **As a Blender add-on** (the GUI case): the user installs it, enables it, and their own Blender
+  opens a local socket and shows a panel saying whether DeepBlend is attached. Every operation then
+  runs in the Blender they are LOOKING AT, which is the whole point of the M6 item — the batch round
+  trip stops being the only shape.
+* **As a headless server** (the case a test can drive): `blender --background --python
+  deepblend_bridge.py -- --socket <path>` serves exactly the same protocol with no GUI at all.
+
+Two entry points rather than two files, because the protocol and the dispatch are one thing: a second
+copy for the headless case would be a second answer to "what does compile_scene do", and it would rot
+first because nothing runs it.
+
+WHAT IT REUSES
+--------------
+`bootstrap.py`'s dispatch, unchanged: the same `ACTIONS` table, the same protocol-version check, the
+same envelope builder, the same per-request process identity. This file adds a TRANSPORT (a socket)
+and a GUI (a panel), not a second implementation.
+
+THE PROTOCOL is the session protocol, one JSON document per line: the product sends
+`{protocolVersion, jobId, action, payload?}`, this answers with the envelope bootstrap.py builds.
+`{"action": "shutdown"}` closes the connection.
+
+Owner: DeepBlend Studio — SPEC §20 M6
+"""
+
+import json
+import os
+import socket
+import sys
+import threading
+
+import bpy  # noqa: F401  — present in Blender; the import is what makes this an add-on module
+
+def _find_bootstrap():
+    """Import `bootstrap` from wherever it actually is, or say what to set.
+
+    MEASURED PROBLEM, and it is the user's case rather than the test's: Blender COPIES an add-on into
+    its own add-ons directory, so the file that lands there is this one ALONE — `bootstrap.py` is not
+    beside it, and `import bootstrap` fails. The headless entry point never sees this, because there
+    the file still sits in the package.
+
+    So the search is: beside me (headless), then the directory an operator points at, then the one a
+    user can paste into the add-on's preferences. When all three miss, the failure names the setting
+    instead of raising an ImportError into a panel that shows nothing.
+    """
+    candidates = [os.path.dirname(os.path.abspath(__file__))]
+    configured = os.environ.get("DEEPBLEND_BOOTSTRAP_DIR", "")
+    if configured:
+        candidates.append(configured)
+    try:
+        preferences = bpy.context.preferences.addons[__name__].preferences
+        if getattr(preferences, "bootstrap_dir", ""):
+            candidates.insert(0, preferences.bootstrap_dir)
+    except Exception:
+        # No preferences yet (headless, or before registration): the other two are enough.
+        pass
+
+    for candidate in candidates:
+        if candidate and os.path.exists(os.path.join(candidate, "bootstrap.py")):
+            if candidate not in sys.path:
+                sys.path.insert(0, candidate)
+            import bootstrap  # noqa: F401
+            return sys.modules["bootstrap"]
+    return None
+
+
+bootstrap = _find_bootstrap()
+BOOTSTRAP_PROBLEM = None if bootstrap is not None else (
+    "bootstrap.py was not found. Set DEEPBLEND_BOOTSTRAP_DIR to the provider package's python "
+    "directory (…/provider-local/python), or paste it into this add-on's preferences."
+)
+
+bl_info = {
+    "name": "DeepBlend Studio Bridge",
+    "author": "DeepBlend Studio",
+    "version": (0, 2, 4),
+    "blender": (4, 0, 0),
+    "location": "View3D > Sidebar > DeepBlend",
+    "description": "Serve DeepBlend operations inside this Blender, so the product drives the window you are looking at",
+    "category": "Scene",
+}
+
+# The default socket path. One per workspace, so two stores on one machine do not collide — and the
+# product passes its own path when it starts the headless server, so this default is only what the
+# add-on uses when a user enables it with no configuration.
+DEFAULT_SOCKET = os.path.join(os.path.expanduser("~"), ".deepblend-bridge.sock")
+
+
+class _Bridge:
+    """The serving state: one socket, one thread, and the last thing that happened."""
+
+    def __init__(self, socket_path, options=None):
+        self.socket_path = socket_path
+        self.options = options or {}
+        self.server = None
+        self.thread = None
+        self.requests = 0
+        self.last_action = None
+        self.last_error = None
+        self.connected = False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def start(self):
+        if os.path.exists(self.socket_path):
+            # A socket file left by a process that died. Refusing to start would leave the user with
+            # no way forward except deleting a file they cannot see, so it is replaced — the same
+            # decision the render job's recovery path makes about a stale pid file.
+            os.unlink(self.socket_path)
+        self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.server.bind(self.socket_path)
+        self.server.listen(4)
+        self.thread = threading.Thread(target=self._serve, name="deepblend-bridge", daemon=True)
+        self.thread.start()
+
+    def stop(self):
+        try:
+            if self.server is not None:
+                self.server.close()
+        except Exception:
+            pass
+        self.server = None
+        try:
+            if os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
+        except Exception:
+            pass
+
+    # -- serving -----------------------------------------------------------
+
+    def _serve(self):
+        while self.server is not None:
+            try:
+                connection, _ = self.server.accept()
+            except Exception:
+                return
+            self.connected = True
+            try:
+                self._converse(connection)
+            except Exception as exc:
+                self.last_error = bootstrap.error_text(exc)
+            finally:
+                self.connected = False
+                try:
+                    connection.close()
+                except Exception:
+                    pass
+
+    def _converse(self, connection):
+        """One connection: a handshake, then a line in and an envelope out, until the peer stops.
+
+        THE HANDSHAKE IS THE SESSION PROTOCOL'S OWN, and it took a hang to notice it was missing: the
+        headless entry point printed `{"kind": "ready"}` to stdout at startup, and a CONNECTION got
+        nothing — so the product's `BlenderSession.ready()` waited forever on a peer that was already
+        serving. A transport that answers the same conversation has to open it the same way.
+        """
+        connection.sendall((json.dumps({"kind": "ready", "pid": os.getpid(), "socket": self.socket_path}) + "\n").encode("utf-8"))
+        buffer = b""
+        while True:
+            chunk = connection.recv(65536)
+            if not chunk:
+                return
+            buffer += chunk
+            while b"\n" in buffer:
+                line, buffer = buffer.split(b"\n", 1)
+                text = line.decode("utf-8", "replace").strip()
+                if text == "":
+                    continue
+                try:
+                    request = json.loads(text)
+                except Exception as exc:
+                    answer = bootstrap.build_envelope(None, None, None, {
+                        "code": "BLENDER_SCRIPT_ERROR",
+                        "message": "the request line is not valid JSON: %s" % (bootstrap.error_text(exc),),
+                    }, [], [])
+                else:
+                    if isinstance(request, dict) and request.get("action") == "shutdown":
+                        connection.sendall((json.dumps({"kind": "bye", "pid": os.getpid()}) + "\n").encode("utf-8"))
+                        return
+                    self.requests += 1
+                    self.last_action = request.get("action") if isinstance(request, dict) else None
+                    answer = bootstrap._session_dispatch(request, self.options)
+                answer["kind"] = "result"
+                connection.sendall((json.dumps(answer, ensure_ascii=False) + "\n").encode("utf-8"))
+
+    # -- what the panel shows ----------------------------------------------
+
+    def status(self):
+        if self.server is None:
+            return "off"
+        return "attached" if self.connected else "listening on %s" % (self.socket_path,)
+
+
+_BRIDGE = None
+
+
+class DeepBlendBridgePreferences(bpy.types.AddonPreferences):
+    """Where the user points the add-on at the package, because Blender copies add-ons alone."""
+
+    bl_idname = __name__
+
+    bootstrap_dir: bpy.props.StringProperty(  # type: ignore[valid-type]
+        name="bootstrap.py directory",
+        description="The provider package's python directory (…/provider-local/python)",
+        default="",
+        subtype="DIR_PATH",
+    )
+
+    def draw(self, context):
+        layout = self.layout
+        layout.prop(self, "bootstrap_dir")
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text=BOOTSTRAP_PROBLEM, icon="ERROR")
+
+
+class DEEPBLEND_PT_bridge(bpy.types.Panel):
+    """The panel, because an add-on a user cannot see is an add-on they will not trust."""
+
+    bl_label = "DeepBlend Studio"
+    bl_idname = "DEEPBLEND_PT_bridge"
+    bl_space_type = "VIEW_3D"
+    bl_region_type = "UI"
+    bl_category = "DeepBlend"
+
+    def draw(self, context):
+        layout = self.layout
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text="bootstrap.py not found", icon="ERROR")
+            layout.label(text="Set it in this add-on's preferences")
+            return
+        if _BRIDGE is None:
+            layout.label(text="Bridge is not running", icon="ERROR")
+            return
+        layout.label(text="Status: %s" % (_BRIDGE.status(),))
+        layout.label(text="Socket: %s" % (os.path.basename(_BRIDGE.socket_path),))
+        layout.label(text="Operations served: %d" % (_BRIDGE.requests,))
+        if _BRIDGE.last_action is not None:
+            layout.label(text="Last: %s" % (_BRIDGE.last_action,))
+        if _BRIDGE.last_error is not None:
+            layout.label(text="Last error: %s" % (_BRIDGE.last_error[:60],), icon="ERROR")
+
+
+def register():
+    global _BRIDGE
+    socket_path = os.environ.get("DEEPBLEND_BRIDGE_SOCKET", DEFAULT_SOCKET)
+    _BRIDGE = _Bridge(socket_path)
+    try:
+        _BRIDGE.start()
+    except Exception as exc:
+        # A bridge that cannot listen must not stop Blender from starting: the user's session is more
+        # important than this panel, and the panel says what went wrong.
+        _BRIDGE.last_error = bootstrap.error_text(exc)
+    bpy.utils.register_class(DeepBlendBridgePreferences)
+    bpy.utils.register_class(DEEPBLEND_PT_bridge)
+
+
+def unregister():
+    global _BRIDGE
+    bpy.utils.unregister_class(DEEPBLEND_PT_bridge)
+    bpy.utils.unregister_class(DeepBlendBridgePreferences)
+    if _BRIDGE is not None:
+        _BRIDGE.stop()
+    _BRIDGE = None
+
+
+def main():
+    """Headless entry point: serve until the process is asked to stop."""
+    argv = sys.argv
+    options = {}
+    if "--" in argv:
+        tokens = argv[argv.index("--") + 1:]
+        index = 0
+        while index < len(tokens):
+            if tokens[index] == "--socket" and index + 1 < len(tokens):
+                options["socket"] = tokens[index + 1]
+                index += 2
+                continue
+            index += 1
+    socket_path = options.get("socket", DEFAULT_SOCKET)
+
+    if bootstrap is None:
+        print(json.dumps({"kind": "error", "message": BOOTSTRAP_PROBLEM}), flush=True)
+        return 2
+
+    global _BRIDGE
+    _BRIDGE = _Bridge(socket_path, {"proc": None})
+    _BRIDGE.start()
+    print(json.dumps({"kind": "ready", "pid": os.getpid(), "socket": socket_path}), flush=True)
+    try:
+        # The serve thread is a daemon, so this loop is what keeps the process alive. A SIGTERM (or
+        # the product closing the socket and asking for shutdown) ends it.
+        _BRIDGE.thread.join()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        _BRIDGE.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())