feat(silo): async save queue — background upload with coalescing (#392)

Local save is synchronous (data safe on disk before returning).
Network upload (file, DAG, BOM) runs in a background QThread.

New files:
- silo_upload_queue.py: UploadTask dataclass + UploadWorker(QThread)
  with coalescing, cancel, shutdown, and Qt signals
- silo_status_widget.py: SyncStatusWidget for status bar feedback

Modified:
- silo_commands.py: _extract_dag_data, _extract_bom_data, _enqueue_upload
  helpers; Silo_Save and Silo_Commit use async enqueue
- silo_origin.py: saveDocument() saves locally then enqueues async upload
- InitGui.py: upload queue init at 700ms, shutdown handler via atexit

Thread safety: worker never accesses App.Document or Qt widgets;
all data pre-extracted on main thread as plain dicts/strings.
Queue uses threading.Lock; signals cross thread boundary via Qt.

.mailmap

@@ -0,0 +1,7 @@
+forbes <contact@kindred-systems.com> forbes <joseph.forbes@kindred-systems.com>
+forbes <contact@kindred-systems.com> forbes <zoe.forbes@kindred-systems.com>
+forbes <contact@kindred-systems.com> forbes-0023 <joseph.forbes@kindred-systems.com>
+forbes <contact@kindred-systems.com> forbes-0023 <zoe.forbes@kindred-systems.com>
+forbes <contact@kindred-systems.com> josephforbes23 <joseph.forbes@kindred-systems.com>
+forbes <contact@kindred-systems.com> Zoe Forbes <forbes@copernicus-9.kindred.internal>
+forbes <contact@kindred-systems.com> admin <admin@kindred-systems.com>

Init.py

@@ -0,0 +1,13 @@
+"""Silo addon — console initialization.
+
+Adds the shared silo-client package to sys.path so that
+``import silo_client`` works from silo_commands.py and other modules.
+"""
+
+import os
+import sys
+
+_mod_dir = os.path.dirname(os.path.abspath(__file__))
+_client_dir = os.path.join(_mod_dir, "silo-client")
+if os.path.isdir(_client_dir) and _client_dir not in sys.path:
+    sys.path.insert(0, _client_dir)

InitGui.py

@@ -0,0 +1,314 @@
+"""Kindred Silo addon — GUI initialization.
+
+Registers the SiloWorkbench, Silo file origin, overlay context,
+dock panels (auth + activity), document observer, and start page override.
+"""
+
+import os
+
+import FreeCAD
+import FreeCADGui
+
+FreeCAD.Console.PrintMessage("Kindred Silo InitGui.py loading...\n")
+
+
+# ---------------------------------------------------------------------------
+# Workbench
+# ---------------------------------------------------------------------------
+
+
+class SiloWorkbench(FreeCADGui.Workbench):
+    """Kindred Silo workbench for item database integration."""
+
+    MenuText = "Kindred Silo"
+    ToolTip = "Item database and part management for Kindred Create"
+    Icon = ""
+
+    def __init__(self):
+        icon_path = os.path.join(
+            os.path.dirname(os.path.abspath(__file__)),
+            "freecad",
+            "resources",
+            "icons",
+            "silo.svg",
+        )
+        if os.path.exists(icon_path):
+            self.__class__.Icon = icon_path
+
+    def Initialize(self):
+        """Called when workbench is first activated."""
+        import silo_commands
+
+        # Register Silo as a file origin in the unified origin system
+        try:
+            import silo_origin
+
+            silo_origin.register_silo_origin()
+        except Exception as e:
+            FreeCAD.Console.PrintWarning(f"Could not register Silo origin: {e}\n")
+
+        # Silo origin toolbar — shown as an overlay on any context when the
+        # active document is Silo-tracked.  Registered as Unavailable so
+        # EditingContextResolver controls visibility via the overlay system.
+        self.silo_toolbar_commands = [
+            "Silo_Commit",
+            "Silo_Pull",
+            "Silo_Push",
+            "Separator",
+            "Silo_Info",
+            "Silo_BOM",
+            "Silo_Jobs",
+        ]
+        self.appendToolbar("Silo Origin", self.silo_toolbar_commands, "Unavailable")
+
+        # Silo menu provides admin/management commands.
+        self.menu_commands = [
+            "Silo_Info",
+            "Silo_BOM",
+            "Silo_Jobs",
+            "Silo_TagProjects",
+            "Silo_SetStatus",
+            "Silo_Rollback",
+            "Silo_SaveAsTemplate",
+            "Separator",
+            "Silo_Settings",
+            "Silo_Auth",
+            "Silo_Runners",
+            "Silo_StartPanel",
+            "Silo_Diag",
+        ]
+
+        self.appendMenu("Silo", self.menu_commands)
+
+    def Activated(self):
+        """Called when workbench is activated."""
+        FreeCAD.Console.PrintMessage("Kindred Silo workbench activated\n")
+        FreeCADGui.runCommand("Silo_StartPanel", 0)
+
+    def Deactivated(self):
+        pass
+
+    def GetClassName(self):
+        return "Gui::PythonWorkbench"
+
+
+FreeCADGui.addWorkbench(SiloWorkbench())
+FreeCAD.Console.PrintMessage("Silo workbench registered\n")
+
+
+# ---------------------------------------------------------------------------
+# Silo overlay context — adds "Silo Origin" toolbar to any active context
+# when the current document is Silo-tracked.
+# ---------------------------------------------------------------------------
+
+
+def _register_silo_overlay():
+    """Register the Silo overlay after the Silo workbench has initialised."""
+
+    def _silo_overlay_match():
+        """Return True if the active document is Silo-tracked."""
+        try:
+            doc = FreeCAD.ActiveDocument
+            if not doc:
+                return False
+            from silo_origin import get_silo_origin
+
+            origin = get_silo_origin()
+            return origin.ownsDocument(doc)
+        except Exception:
+            return False
+
+    try:
+        from kindred_sdk import register_overlay
+
+        register_overlay(
+            "silo",  # overlay id
+            ["Silo Origin"],  # toolbar names to append
+            _silo_overlay_match,  # match function
+        )
+    except Exception as e:
+        FreeCAD.Console.PrintWarning(f"Silo overlay registration failed: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# Document observer — builds the Silo metadata tree when .kc files open.
+# ---------------------------------------------------------------------------
+
+
+def _register_silo_document_observer():
+    """Register the Silo document observer for .kc tree building."""
+    try:
+        import silo_document
+
+        silo_document.register()
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: document observer registration skipped: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# Dock panels — auth and activity widgets via SDK
+# ---------------------------------------------------------------------------
+
+
+def _setup_silo_auth_panel():
+    """Dock the Silo authentication panel in the right-hand side panel."""
+    try:
+        from kindred_sdk import register_dock_panel
+
+        def _factory():
+            import silo_commands
+
+            auth = silo_commands.SiloAuthDockWidget()
+            # Prevent GC of the auth timer by stashing on the widget
+            auth.widget._auth = auth
+            return auth.widget
+
+        register_dock_panel("SiloDatabaseAuth", "Database Auth", _factory)
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: auth panel skipped: {e}\n")
+
+
+def _setup_silo_activity_panel():
+    """Show a dock widget with recent Silo database activity."""
+    try:
+        from kindred_sdk import register_dock_panel
+
+        def _factory():
+            from PySide import QtWidgets
+
+            widget = QtWidgets.QWidget()
+            layout = QtWidgets.QVBoxLayout(widget)
+            activity_list = QtWidgets.QListWidget()
+            layout.addWidget(activity_list)
+
+            try:
+                import silo_commands
+
+                items = silo_commands._client.list_items()
+                if isinstance(items, list):
+                    for item in items[:20]:
+                        pn = item.get("part_number", "")
+                        desc = item.get("description", "")
+                        updated = item.get("updated_at", "")
+                        if updated:
+                            updated = updated[:10]
+                        activity_list.addItem(f"{pn} - {desc} - {updated}")
+                if activity_list.count() == 0:
+                    activity_list.addItem("(No items in database)")
+            except Exception:
+                activity_list.addItem("(Unable to connect to Silo database)")
+
+            return widget
+
+        register_dock_panel("SiloDatabaseActivity", "Database Activity", _factory)
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: activity panel skipped: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# First-start check
+# ---------------------------------------------------------------------------
+
+
+def _check_silo_first_start():
+    """Show Silo settings dialog on first startup if not yet configured."""
+    try:
+        param = FreeCAD.ParamGet("User parameter:BaseApp/Preferences/Mod/KindredSilo")
+        if not param.GetBool("FirstStartChecked", False):
+            param.SetBool("FirstStartChecked", True)
+            if not param.GetString("ApiUrl", ""):
+                FreeCADGui.runCommand("Silo_Settings")
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: first-start check skipped: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# Start page override — must happen before the C++ StartLauncher fires
+# at ~100ms after GUI init.
+# ---------------------------------------------------------------------------
+
+try:
+    import silo_start
+
+    silo_start.register()
+except Exception as e:
+    FreeCAD.Console.PrintWarning(f"Silo Start page override failed: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# Handle kindred:// URLs passed as command-line arguments on cold start.
+# ---------------------------------------------------------------------------
+
+
+def _handle_startup_urls():
+    """Process any kindred:// URLs passed as command-line arguments."""
+    import sys
+
+    from silo_commands import handle_kindred_url
+
+    for arg in sys.argv[1:]:
+        if arg.startswith("kindred://"):
+            handle_kindred_url(arg)
+
+
+# ---------------------------------------------------------------------------
+# Upload queue — background thread for async file uploads
+# ---------------------------------------------------------------------------
+
+
+def _setup_upload_queue():
+    """Start the upload queue and register the status bar widget."""
+    try:
+        from silo_upload_queue import get_upload_queue
+
+        queue = get_upload_queue()
+
+        # Status bar widget
+        try:
+            from silo_status_widget import SyncStatusWidget
+
+            mw = FreeCADGui.getMainWindow()
+            if mw and mw.statusBar():
+                widget = SyncStatusWidget(queue, parent=mw.statusBar())
+                mw.statusBar().addPermanentWidget(widget)
+        except Exception as e:
+            FreeCAD.Console.PrintLog(f"Silo: status widget skipped: {e}\n")
+
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: upload queue skipped: {e}\n")
+
+
+def _shutdown_upload_queue():
+    """Drain the upload queue on application exit."""
+    try:
+        from silo_upload_queue import shutdown_upload_queue
+
+        shutdown_upload_queue()
+    except Exception:
+        pass
+
+
+def _register_shutdown_handler():
+    """Connect the upload queue shutdown to application exit."""
+    try:
+        import atexit
+
+        atexit.register(_shutdown_upload_queue)
+    except Exception as e:
+        FreeCAD.Console.PrintLog(f"Silo: shutdown handler skipped: {e}\n")
+
+
+# ---------------------------------------------------------------------------
+# Deferred setup — staggered timers for non-blocking startup
+# ---------------------------------------------------------------------------
+
+from PySide import QtCore as _QtCore
+
+_QtCore.QTimer.singleShot(500, _handle_startup_urls)
+_QtCore.QTimer.singleShot(600, _register_silo_document_observer)
+_QtCore.QTimer.singleShot(700, _setup_upload_queue)
+_QtCore.QTimer.singleShot(800, _register_shutdown_handler)
+_QtCore.QTimer.singleShot(2000, _setup_silo_auth_panel)
+_QtCore.QTimer.singleShot(2500, _register_silo_overlay)
+_QtCore.QTimer.singleShot(3000, _check_silo_first_start)
+_QtCore.QTimer.singleShot(4000, _setup_silo_activity_panel)

freecad/silo_commands.py

@@ -920,6 +920,67 @@ def _push_bom_after_upload(doc, part_number, revision_number):
         FreeCAD.Console.PrintWarning(f"BOM sync failed: {e}\n")
 
 
+def _extract_dag_data(doc):
+    """Pre-extract DAG data on the main thread for async upload.
+
+    Returns ``(nodes, edges)`` or ``None`` if extraction fails or
+    the document has no meaningful DAG.
+    """
+    try:
+        from dag import extract_dag
+
+        nodes, edges = extract_dag(doc)
+        return (nodes, edges) if nodes else None
+    except Exception:
+        return None
+
+
+def _extract_bom_data(doc):
+    """Pre-extract BOM entries on the main thread for async upload.
+
+    Returns a list of resolved :class:`bom_sync.BomEntry` objects
+    (with ``part_number`` populated) or ``None`` if the document is
+    not an assembly or has no cross-document links.
+
+    Resolution calls ``_client.get_item_by_uuid()`` which is a fast
+    DB lookup.  This must run on the main thread because it accesses
+    ``App.Document`` objects to read ``SiloItemId`` properties.
+    """
+    try:
+        from bom_sync import extract_bom_entries, resolve_entries
+
+        entries = extract_bom_entries(doc)
+        if not entries:
+            return None
+        resolved, _unresolved = resolve_entries(entries, _client)
+        return resolved if resolved else None
+    except Exception:
+        return None
+
+
+def _enqueue_upload(doc, part_number, file_path, properties, comment=""):
+    """Capture all upload data on the main thread and enqueue for async upload.
+
+    The caller must have already saved the file to *file_path* and
+    collected *properties* synchronously.
+    """
+    from silo_upload_queue import UploadTask, get_upload_queue
+
+    dag_data = _extract_dag_data(doc)
+    bom_data = _extract_bom_data(doc)
+
+    task = UploadTask(
+        doc_name=doc.Name,
+        part_number=part_number,
+        file_path=str(file_path),
+        properties=properties,
+        comment=comment,
+        dag_data=dag_data,
+        bom_data=bom_data,
+    )
+    get_upload_queue().enqueue(task)
+
+
 class Silo_Save:
     """Save locally and upload to the server."""
 
@@ -981,22 +1042,8 @@ class Silo_Save:
 
         FreeCAD.Console.PrintMessage(f"Saved: {file_path}\n")
 
-        # Try to upload to server
-        try:
-            result = _client._upload_file(
-                part_number, str(file_path), properties, "Auto-save"
-            )
-
-            new_rev = result["revision_number"]
-            FreeCAD.Console.PrintMessage(f"Uploaded as revision {new_rev}\n")
-
-            _push_dag_after_upload(doc, part_number, new_rev)
-            _push_bom_after_upload(doc, part_number, new_rev)
-            _update_manifest_revision(str(file_path), new_rev)
-
-        except Exception as e:
-            FreeCAD.Console.PrintWarning(f"Upload failed: {e}\n")
-            FreeCAD.Console.PrintMessage("File saved locally but not uploaded.\n")
+        # Enqueue async upload (non-blocking)
+        _enqueue_upload(doc, part_number, file_path, properties, comment="Auto-save")
 
     def IsActive(self):
         return FreeCAD.ActiveDocument is not None and _server_mode == "normal"
@@ -1036,24 +1083,23 @@ class Silo_Commit:
         # Collect properties BEFORE saving to avoid dirtying the document
         properties = collect_document_properties(doc)
 
-        try:
-            file_path = _sync.save_to_canonical_path(doc, force_rename=True)
-            if not file_path:
-                return
+        file_path = _sync.save_to_canonical_path(doc, force_rename=True)
+        if not file_path:
+            FreeCAD.Console.PrintError("Could not determine save path\n")
+            return
 
-            result = _client._upload_file(
-                part_number, str(file_path), properties, comment
-            )
+        # Clear modified flag — data is safe on disk
+        gui_doc = FreeCADGui.getDocument(doc.Name)
+        if gui_doc and gui_doc.Modified:
+            try:
+                gui_doc.Modified = False
+            except Exception:
+                pass
 
-            new_rev = result["revision_number"]
-            FreeCAD.Console.PrintMessage(f"Committed revision {new_rev}: {comment}\n")
+        FreeCAD.Console.PrintMessage(f"Saved: {file_path}\n")
 
-            _push_dag_after_upload(doc, part_number, new_rev)
-            _push_bom_after_upload(doc, part_number, new_rev)
-            _update_manifest_revision(str(file_path), new_rev)
-
-        except Exception as e:
-            FreeCAD.Console.PrintError(f"Commit failed: {e}\n")
+        # Enqueue async upload (non-blocking)
+        _enqueue_upload(doc, part_number, file_path, properties, comment=comment)
 
     def IsActive(self):
         return FreeCAD.ActiveDocument is not None and _server_mode == "normal"

freecad/silo_origin.py

@@ -357,16 +357,17 @@ class SiloOrigin:
             return None
 
     def saveDocument(self, doc) -> bool:
-        """Save document and sync to Silo.
+        """Save document locally and enqueue async upload to Silo.
 
-        Saves the document locally to the canonical path and uploads
-        to Silo for sync.
+        The local save is synchronous — the user's data is safe on disk
+        before this method returns.  The network upload (file, DAG, BOM)
+        runs in a background thread via the upload queue.
 
         Args:
             doc: FreeCAD App.Document
 
         Returns:
-            True if save succeeded
+            True if the local save succeeded
         """
         if not doc:
             return False
@@ -380,21 +381,25 @@ class SiloOrigin:
             return False
 
         try:
-            # Save to canonical path
+            # 1. Synchronous: save to disk
             file_path = _sync.save_to_canonical_path(doc)
             if not file_path:
                 FreeCAD.Console.PrintError("Failed to save to canonical path\n")
                 return False
 
-            # Upload to Silo
+            # 2. Synchronous: collect all data needed for upload
             properties = collect_document_properties(doc)
-            _client._upload_file(obj.SiloPartNumber, str(file_path), properties, comment="")
 
-            # Clear modified flag (Modified is on Gui.Document, not App.Document)
+            # 3. Synchronous: clear modified flag (data is safe on disk)
             gui_doc = FreeCADGui.getDocument(doc.Name)
             if gui_doc:
                 gui_doc.Modified = False
 
+            # 4. Async: enqueue upload (non-blocking)
+            from silo_commands import _enqueue_upload
+
+            _enqueue_upload(doc, obj.SiloPartNumber, file_path, properties, comment="")
+
             return True
         except Exception as e:
             import traceback

freecad/silo_status_widget.py

@@ -0,0 +1,61 @@
+"""Status bar widget for the Silo upload queue.
+
+Shows sync progress in the main window status bar:
+- Hidden when idle
+- "Syncing PN-001..." during upload
+- "Synced PN-001 r3" briefly on success
+- "Sync failed: PN-001" in red on failure
+"""
+
+from PySide6.QtCore import QTimer
+from PySide6.QtWidgets import QLabel
+
+
+class SyncStatusWidget(QLabel):
+    """Compact status bar indicator for background Silo uploads."""
+
+    _FADE_MS = 4000  # how long the success message stays visible
+
+    def __init__(self, queue, parent=None):
+        super().__init__(parent)
+        self.setVisible(False)
+        self._queue = queue
+        self._fade_timer = QTimer(self)
+        self._fade_timer.setSingleShot(True)
+        self._fade_timer.timeout.connect(self._hide)
+
+        queue.upload_started.connect(self._on_started)
+        queue.upload_finished.connect(self._on_finished)
+        queue.upload_failed.connect(self._on_failed)
+
+    # -- slots ---------------------------------------------------------------
+
+    def _on_started(self, doc_name: str, part_number: str) -> None:
+        pending = self._queue.pending_count
+        if pending > 0:
+            self.setText(f"Syncing {part_number} (+{pending} queued)...")
+        else:
+            self.setText(f"Syncing {part_number}...")
+        self.setStyleSheet("")
+        self._fade_timer.stop()
+        self.setVisible(True)
+
+    def _on_finished(self, doc_name: str, part_number: str, revision: int) -> None:
+        pending = self._queue.pending_count
+        if pending > 0:
+            self.setText(f"Synced {part_number} r{revision}  ({pending} remaining)")
+        else:
+            self.setText(f"Synced {part_number} r{revision}")
+        self.setStyleSheet("")
+        self._fade_timer.start(self._FADE_MS)
+
+    def _on_failed(self, doc_name: str, part_number: str, error: str) -> None:
+        self.setText(f"Sync failed: {part_number}")
+        self.setToolTip(error)
+        self.setStyleSheet("color: #f38ba8;")  # Catppuccin Mocha red
+        self._fade_timer.stop()
+        self.setVisible(True)
+
+    def _hide(self) -> None:
+        self.setVisible(False)
+        self.setToolTip("")

freecad/silo_upload_queue.py

@@ -0,0 +1,250 @@
+"""Async upload queue for Silo PLM.
+
+Provides a background ``QThread`` that processes file uploads, DAG syncs,
+and BOM syncs without blocking the main UI thread.  All data required for
+an upload is captured on the main thread before enqueuing — the worker
+never accesses ``App.Document``, ``Gui.Document``, or any Qt widget.
+
+Typical usage from ``SiloOrigin.saveDocument``::
+
+    task = UploadTask(
+        doc_name=doc.Name,
+        part_number=obj.SiloPartNumber,
+        file_path=str(saved_path),
+        properties=collected_props,
+        comment="",
+        dag_data=extracted_dag,
+        bom_data=extracted_bom,
+    )
+    get_upload_queue().enqueue(task)
+"""
+
+import collections
+import dataclasses
+import threading
+import time
+
+import FreeCAD
+from PySide6.QtCore import QThread, Signal
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class UploadTask:
+    """Immutable snapshot of everything needed to upload a document revision.
+
+    All fields are plain Python types — no FreeCAD or Qt objects.
+    """
+
+    doc_name: str
+    """FreeCAD document internal name (used for coalescing)."""
+
+    part_number: str
+    """Silo part number."""
+
+    file_path: str
+    """Absolute path to the saved ``.kc`` file on disk."""
+
+    properties: dict
+    """Pre-collected document properties dict."""
+
+    comment: str = ""
+    """Revision comment (empty for auto-save)."""
+
+    dag_data: tuple | None = None
+    """Pre-extracted ``(nodes, edges)`` or ``None``."""
+
+    bom_data: object | None = None
+    """Pre-extracted BOM payload or ``None``."""
+
+    timestamp: float = dataclasses.field(default_factory=time.time)
+    """Time the task was created (``time.time()``)."""
+
+
+# ---------------------------------------------------------------------------
+# Worker thread
+# ---------------------------------------------------------------------------
+
+
+class UploadWorker(QThread):
+    """Background thread that processes :class:`UploadTask` items serially.
+
+    Signals are emitted on completion so the main thread can update the UI.
+    The worker never touches FreeCAD documents or Qt widgets.
+    """
+
+    upload_started = Signal(str, str)  # doc_name, part_number
+    upload_finished = Signal(str, str, int)  # doc_name, part_number, revision
+    upload_failed = Signal(str, str, str)  # doc_name, part_number, error
+    queue_empty = Signal()
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self._queue: collections.deque[UploadTask] = collections.deque()
+        self._lock = threading.Lock()
+        self._event = threading.Event()
+        self._stop = False
+
+    # -- public API (called from main thread) --------------------------------
+
+    def enqueue(self, task: UploadTask) -> None:
+        """Add a task, coalescing any pending task for the same document."""
+        with self._lock:
+            self._queue = collections.deque(t for t in self._queue if t.doc_name != task.doc_name)
+            self._queue.append(task)
+        self._event.set()
+
+    def cancel(self, doc_name: str) -> None:
+        """Remove any pending (not yet started) task for *doc_name*."""
+        with self._lock:
+            self._queue = collections.deque(t for t in self._queue if t.doc_name != doc_name)
+
+    @property
+    def pending_count(self) -> int:
+        """Number of tasks waiting to be processed."""
+        with self._lock:
+            return len(self._queue)
+
+    def shutdown(self) -> None:
+        """Signal the worker to stop and wait up to 5 s for it to finish."""
+        self._stop = True
+        self._event.set()
+        self.wait(5000)
+
+    # -- thread entry point --------------------------------------------------
+
+    def run(self) -> None:  # noqa: D401 — Qt override
+        """Process tasks until :meth:`shutdown` is called."""
+        from silo_commands import _client, _update_manifest_revision
+
+        while not self._stop:
+            self._event.wait(timeout=1.0)
+            self._event.clear()
+
+            while not self._stop:
+                task = self._pop_task()
+                if task is None:
+                    break
+                self._process(task, _client)
+
+            if not self._stop and self.pending_count == 0:
+                self.queue_empty.emit()
+
+    # -- internals -----------------------------------------------------------
+
+    def _pop_task(self) -> UploadTask | None:
+        with self._lock:
+            return self._queue.popleft() if self._queue else None
+
+    def _process(self, task: UploadTask, client) -> None:
+        self.upload_started.emit(task.doc_name, task.part_number)
+        try:
+            result = client._upload_file(
+                task.part_number, task.file_path, task.properties, task.comment
+            )
+            rev = result.get("revision_number", 0)
+
+            # DAG sync (non-critical)
+            if task.dag_data:
+                try:
+                    nodes, edges = task.dag_data
+                    client.push_dag(task.part_number, rev, nodes, edges)
+                except Exception as exc:
+                    FreeCAD.Console.PrintWarning(
+                        f"[upload-queue] DAG sync failed for {task.part_number}: {exc}\n"
+                    )
+
+            # BOM sync (non-critical)
+            if task.bom_data:
+                try:
+                    _push_bom_from_extracted(task.part_number, task.bom_data, client)
+                except Exception as exc:
+                    FreeCAD.Console.PrintWarning(
+                        f"[upload-queue] BOM sync failed for {task.part_number}: {exc}\n"
+                    )
+
+            # Manifest revision update (local file I/O, safe from worker)
+            try:
+                from silo_commands import _update_manifest_revision
+
+                _update_manifest_revision(task.file_path, rev)
+            except Exception:
+                pass
+
+            self.upload_finished.emit(task.doc_name, task.part_number, rev)
+            FreeCAD.Console.PrintMessage(
+                f"[upload-queue] Uploaded {task.part_number} as revision {rev}\n"
+            )
+
+        except Exception as exc:
+            self.upload_failed.emit(task.doc_name, task.part_number, str(exc))
+            FreeCAD.Console.PrintWarning(
+                f"[upload-queue] Upload failed for {task.part_number}: {exc}\n"
+            )
+
+
+def _push_bom_from_extracted(part_number: str, bom_data, client) -> None:
+    """Diff and apply pre-extracted BOM entries against the server.
+
+    *bom_data* is a list of resolved ``bom_sync.BomEntry`` dataclasses
+    (with ``part_number`` populated) produced by
+    :func:`silo_commands._extract_bom_data` on the main thread.
+
+    This function fetches the current server BOM, diffs it against the
+    local entries, and applies adds/quantity updates.  No FreeCAD
+    document access is needed — safe to call from the worker thread.
+    """
+    if not bom_data:
+        return
+    from bom_sync import apply_bom_diff, diff_bom
+
+    try:
+        remote = client.get_bom(part_number)
+    except Exception:
+        remote = []
+
+    diff = diff_bom(bom_data, remote)
+    result = apply_bom_diff(diff, part_number, client)
+
+    parts = []
+    if result.added_count:
+        parts.append(f"+{result.added_count} added")
+    if result.updated_count:
+        parts.append(f"~{result.updated_count} qty updated")
+    if parts:
+        FreeCAD.Console.PrintMessage(
+            f"[upload-queue] BOM synced for {part_number}: {', '.join(parts)}\n"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_upload_queue: UploadWorker | None = None
+
+
+def get_upload_queue() -> UploadWorker:
+    """Return the global upload queue, creating it on first call."""
+    global _upload_queue
+    if _upload_queue is None:
+        _upload_queue = UploadWorker()
+        _upload_queue.start()
+    return _upload_queue
+
+
+def shutdown_upload_queue() -> None:
+    """Stop the global upload queue if running."""
+    global _upload_queue
+    if _upload_queue is not None:
+        count = _upload_queue.pending_count
+        if count:
+            FreeCAD.Console.PrintWarning(
+                f"[upload-queue] Waiting for {count} pending upload(s)...\n"
+            )
+        _upload_queue.shutdown()
+        _upload_queue = None

package.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
+  <name>silo</name>
+  <description>PLM workbench for Kindred Create</description>
+  <version>0.1.0</version>
+  <maintainer email="development@kindred-systems.com">Kindred Systems</maintainer>
+  <license file="LICENSE">MIT</license>
+  <url type="repository">https://git.kindred-systems.com/kindred/silo-mod</url>
+
+  <content>
+    <workbench>
+      <classname>SiloWorkbench</classname>
+      <subdirectory>freecad</subdirectory>
+    </workbench>
+  </content>
+
+  <kindred>
+    <min_create_version>0.1.0</min_create_version>
+    <load_priority>60</load_priority>
+    <pure_python>true</pure_python>
+    <dependencies>
+      <dependency>sdk</dependency>
+    </dependencies>
+  </kindred>
+</package>