agentstreamdeck 2.1.1__py3-none-any.whl

ocdeck/diagnostics.py

@@ -0,0 +1,227 @@
+"""Read-only diagnostics and an allowlisted, redacted issue bundle."""
+
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import zipfile
+from . import __version__
+from .common import home, read_json, request, load_config
+from .observability import tail
+from .security import scrub
+
+
+def versions():
+    node = shutil.which("node")
+    try:
+        node_version = (
+            subprocess.run([node, "--version"], capture_output=True, text=True, timeout=3, check=True).stdout.strip()
+            if node
+            else "missing"
+        )
+    except (OSError, subprocess.SubprocessError):
+        node_version = "unavailable"
+    return {
+        "agentdeck": __version__,
+        "python": platform.python_version(),
+        "node": node_version,
+        "os": platform.platform(),
+    }
+
+
+def doctor(project=".", no_device=False, root=None):
+    root = Path(root or home())
+    project = Path(project).resolve()
+    rows = []
+
+    def add(check, ok, detail, fix):
+        rows.append(
+            {
+                "check": check,
+                "result": "PASS" if ok is True else "FAIL" if ok is False else "MANUAL",
+                "detail": detail,
+                "fix": fix,
+            }
+        )
+
+    ver = versions()
+    try:
+        node_ok = int(ver["node"].lstrip("v").split(".")[0]) >= 20
+    except ValueError:
+        node_ok = False
+    add("node", node_ok, ver["node"], "Install Node.js 20+, then restart the terminal.")
+    config_file = root / "config.json"
+    try:
+        config = load_config(root)
+    except (ValueError, OSError):
+        config = None
+    add(
+        "config",
+        isinstance(config, dict),
+        "JSON configuration",
+        "Repair config.json as a JSON object; ocdeck appearance --dry-run",
+    )
+    from .settings import validate_config
+
+    try:
+        validate_config(config)
+        add("config-values", True, "Validated broker and appearance settings", "ocdeck appearance --dry-run")
+    except (ValueError, TypeError) as error:
+        add("config-values", False, str(error), "Repair config.json; ocdeck appearance --dry-run")
+    if os.name == "nt":
+        add(
+            "windows-terminal",
+            bool(shutil.which("wt.exe")),
+            "Dedicated-window launcher",
+            "Install Windows Terminal; restart the terminal.",
+        )
+    from .harness import SOURCE
+
+    add(
+        "runtime-assets",
+        (SOURCE / "plugins/harnesses/hook.mjs").is_file() and (SOURCE / "scripts/Run-OpenCode.ps1").is_file(),
+        "Packaged adapter and launcher sources",
+        "python -m pip install --force-reinstall agentstreamdeck",
+    )
+    try:
+        status = request("GET", "/v1/status", root=root)
+        add("broker", True, "Local authenticated API responds", "ocdeck broker")
+    except Exception:
+        status = {}
+        add("broker", False, "Local broker unavailable", "ocdeck broker")
+    add(
+        "capacity",
+        not status.get("overflow"),
+        f"Overflow: {status.get('overflow', 0)}",
+        "Close unused sessions or attach a larger deck.",
+    )
+    if not no_device:
+        from .device import enumerate_devices, elgato_running
+
+        add(
+            "elgato",
+            not elgato_running(),
+            "Elgato process ownership check",
+            "Quit Stream Deck from its tray menu; ocdeck devices",
+        )
+        try:
+            devices = enumerate_devices()
+            device_config = config if isinstance(config, dict) else {}
+            selected = [
+                d
+                for d in devices
+                if not device_config.get("serial") or d.get("serial_number") == device_config["serial"]
+            ]
+            add(
+                "device",
+                len(selected) == 1,
+                f"{len(selected)} matching devices",
+                "ocdeck devices; select serial in config.json if multiple.",
+            )
+            if status:
+                add(
+                    "device-online",
+                    status.get("device", {}).get("online") is True,
+                    status.get("device", {}).get("error", ""),
+                    "Release Elgato ownership and reconnect USB; ocdeck broker",
+                )
+        except Exception as error:
+            add("device", False, str(error), "python -m pip install --upgrade agentstreamdeck; ocdeck devices")
+    receipts = list((project / ".agentdeck").glob("*.json"))
+    add(
+        "hooks-installed",
+        bool(receipts),
+        f"{len(receipts)} receipts in project",
+        "ocdeck harness-install PROFILE --project PROJECT",
+    )
+    for receipt in receipts:
+        saved = read_json(receipt)
+        target = Path(saved.get("target", "")) if isinstance(saved, dict) else Path()
+        from .harness import PROFILES
+
+        profile = receipt.stem
+        expected = {
+            "claude": ".claude/settings.local.json",
+            "gemini": ".gemini/settings.json",
+            "cursor": ".cursor/hooks.json",
+            "copilot-cli": ".github/hooks/agentdeck-copilot-cli.json",
+            "copilot-vscode": ".github/hooks/agentdeck-copilot-vscode.json",
+            "codex": ".codex/hooks.json",
+        }.get(profile)
+        good = bool(expected) and target == project / expected
+        actual = read_json(target) if good else None
+        good = good and isinstance(actual, dict) and isinstance(actual.get("hooks"), dict)
+        if good and isinstance(saved, dict) and isinstance(actual, dict):
+            for event, entries in saved.get("configuration", {}).get("hooks", {}).items():
+                good = good and all(entry in actual["hooks"].get(event, []) for entry in entries)
+        add(
+            "hooks-" + profile,
+            bool(good),
+            "Receipt target and installed entries",
+            f'ocdeck harness-install {profile} --project "{project}" --dry-run',
+        )
+    details = [s.get("detail", "") for s in status.get("slots", [])]
+    add(
+        "hook-delivery",
+        not any("failed" in d.lower() for d in details),
+        "Hook delivery failure latch",
+        "Restart the managed session after fixing native hook errors.",
+    )
+    add(
+        "first-hook",
+        not any("Waiting for first" in d for d in details),
+        "First native hook received",
+        "Submit a prompt; review native hooks and workspace trust.",
+    )
+    focus = status.get("lastFocus")
+    add(
+        "focus",
+        focus.get("ok") if focus else None,
+        "Last focus result" if focus else "No focus attempt recorded",
+        "ocdeck focus 1; use a dedicated managed window under the same Windows user.",
+    )
+    # Runtime policy and interactive behavior cannot be proved from static files.
+    manual = {
+        "approval-coverage": "Inspect HARNESSES.md; unpaired approval notifications cannot establish counts.",
+        "stale-native-hooks": "Verify prompt/tool/stop hooks in the native runtime; heartbeat does not prove hook coverage.",
+        "bridge-restart": "After a broker restart, verify managed Node bridge and supervisor processes remain alive.",
+        "foreground-policy": "Test minimized windows; run broker and agents at the same elevation.",
+        "vscode-signin": "Sign in and enable Copilot in the isolated managed VS Code profile.",
+        "vscode-trust": "Inspect Chat: Configure Hooks and workspace trust.",
+        "vscode-title": "Preserve the managed window.title and launcher suffix.",
+        "jsonc": "Preserve comments; reconcile JSONC manually before harness-install.",
+        "moved-project": "If moved, reconcile old hooks and receipt; do not blindly rewrite the recorded target.",
+        "powershell-policy": "Use the trusted FIRST-RUN.md invocation subject to device policy.",
+        "opencode-shim": "Run Get-Command opencode in PowerShell; use ocdeck launch if an alias wins.",
+        "deleted-checkout": "Keep the installed source or reinstall hooks to the new source before removing it.",
+        "homeailab-focus": "Use the managed wrapper and retain the Windows Terminal managed tab title.",
+        "notifications": "Enable AgentStreamDeck notifications in Windows Settings; test a real identified question with Focus Assist on and off.",
+    }
+    for key, fix in manual.items():
+        add(key, None, "Interactive verification required", fix)
+    return scrub(rows)
+
+
+def report(output, lines=100, root=None):
+    root = Path(root or home())
+    try:
+        token = (root / "token").read_text().strip()
+    except OSError:
+        token = ""
+    try:
+        status = request("GET", "/v1/status", root=root)
+    except Exception:
+        status = {"error": "Broker unavailable"}
+    values = {
+        "status.json": status,
+        "versions.json": versions(),
+        "config.json": read_json(root / "config.json", {}),
+        "logs.json": tail(root, lines),
+    }
+    # Deliberately exclude token, discovery, launch descriptors and native configs.
+    with zipfile.ZipFile(output, "x", compression=zipfile.ZIP_DEFLATED) as archive:
+        for name, value in values.items():
+            archive.writestr(name, json.dumps(scrub(value, (token,)), indent=2))
+    return str(Path(output).resolve())

ocdeck/errors.py

@@ -0,0 +1,22 @@
+"""Stable user-facing errors, actionable commands and documentation anchors."""
+
+CATALOG = {
+    "AD001": ("Elgato Stream Deck may own the device", "Quit Stream Deck from the tray; ocdeck doctor"),
+    "AD002": ("Device unavailable or disconnected", "ocdeck devices"),
+    "AD003": ("Broker unavailable", "ocdeck broker"),
+    "AD004": ("Invalid configuration or request", "ocdeck doctor --no-device"),
+    "AD005": ("Stale session registration", "ocdeck status --json; restart the managed agent launcher"),
+    "AD006": ("Focus failed", "ocdeck doctor; ocdeck focus 1"),
+    "AD007": (
+        "Local authentication rejected",
+        "ocdeck doctor --no-device; restart the managed launcher under the broker user",
+    ),
+    "AD008": ("Broker lock unavailable", "ocdeck status --json"),
+    "AD500": ("Unexpected broker error", "ocdeck report --output agentdeck-report.zip"),
+}
+DOC = "https://github.com/darkmatter2222/AgentStreamDeck/blob/main/docs/TROUBLESHOOTING.md"
+
+
+def message(code: str, detail: str = "") -> str:
+    title, fix = CATALOG[code]
+    return f"{code}: {title}. {detail} Fix/check: {fix}. {DOC}"

ocdeck/focus.py

@@ -0,0 +1,156 @@
+"""Focus existing Windows top-level windows; never launch from a press."""
+
+import ctypes
+from ctypes import wintypes
+import os
+import time
+
+
+def activate(record):
+    if os.name != "nt":
+        return {"ok": False, "reason": "Windows host required"}
+    u = ctypes.WinDLL("user32", use_last_error=True)
+    u.GetForegroundWindow.restype = wintypes.HWND
+    u.IsWindowVisible.argtypes = [wintypes.HWND]
+    u.IsIconic.argtypes = [wintypes.HWND]
+    u.ShowWindow.argtypes = [wintypes.HWND, ctypes.c_int]
+    u.SetForegroundWindow.argtypes = [wintypes.HWND]
+    u.GetWindowTextLengthW.argtypes = [wintypes.HWND]
+    u.GetWindowTextW.argtypes = [wintypes.HWND, wintypes.LPWSTR, ctypes.c_int]
+    u.GetWindowThreadProcessId.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
+    u.GetWindowThreadProcessId.restype = wintypes.DWORD
+    callback_type = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
+    u.EnumWindows.argtypes = [callback_type, wintypes.LPARAM]
+    # Declare every HWND argument/result explicitly for 64-bit Python.
+    for name in ("IsWindow", "IsHungAppWindow"):
+        getattr(u, name).argtypes = [wintypes.HWND]
+        getattr(u, name).restype = wintypes.BOOL
+    u.IsChild.argtypes = [wintypes.HWND, wintypes.HWND]
+    u.IsChild.restype = wintypes.BOOL
+    u.ShowWindowAsync.argtypes = [wintypes.HWND, ctypes.c_int]
+    u.ShowWindowAsync.restype = wintypes.BOOL
+    u.GetGUIThreadInfo.argtypes = [wintypes.DWORD, ctypes.POINTER(GUIThreadInfo)]
+    u.GetGUIThreadInfo.restype = wintypes.BOOL
+    u.PeekMessageW.argtypes = [ctypes.POINTER(wintypes.MSG), wintypes.HWND, wintypes.UINT, wintypes.UINT, wintypes.UINT]
+    u.PeekMessageW.restype = wintypes.BOOL
+    u.AttachThreadInput.argtypes = [wintypes.DWORD, wintypes.DWORD, wintypes.BOOL]
+    u.AttachThreadInput.restype = wintypes.BOOL
+    u.BringWindowToTop.argtypes = [wintypes.HWND]
+    u.BringWindowToTop.restype = wintypes.BOOL
+    for name in ("SetFocus", "SetActiveWindow"):
+        getattr(u, name).argtypes = [wintypes.HWND]
+        getattr(u, name).restype = wintypes.HWND
+    token = record.get("windowToken", "")
+    candidates = []
+
+    @callback_type
+    def collect(hwnd, _):
+        if not u.IsWindowVisible(hwnd):
+            return True
+        text = ctypes.create_unicode_buffer(u.GetWindowTextLengthW(hwnd) + 1)
+        u.GetWindowTextW(hwnd, text, len(text))
+        pid = wintypes.DWORD()
+        u.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+        if (token and text.value == token) or (not token and pid.value == record["process"]["pid"]):
+            candidates.append(hwnd)
+        return True
+
+    u.EnumWindows(collect, 0)
+    if len(candidates) != 1:
+        return {
+            "ok": False,
+            "reason": "Window mapping ambiguous or absent; use ocdeck launch for a dedicated window",
+            "matches": len(candidates),
+        }
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel.GetCurrentThreadId.restype = wintypes.DWORD
+    return focus_window(u, kernel.GetCurrentThreadId(), candidates[0])
+
+
+class GUIThreadInfo(ctypes.Structure):
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("flags", wintypes.DWORD),
+        ("hwndActive", wintypes.HWND),
+        ("hwndFocus", wintypes.HWND),
+        ("hwndCapture", wintypes.HWND),
+        ("hwndMenuOwner", wintypes.HWND),
+        ("hwndMoveSize", wintypes.HWND),
+        ("hwndCaret", wintypes.HWND),
+        ("rcCaret", wintypes.RECT),
+    ]
+
+
+def focus_window(u, current, hwnd, sleep=time.sleep):
+    """Activate a resolved window; input attachment is temporary and always undone."""
+    target = u.GetWindowThreadProcessId(hwnd, None)
+    if not target or not u.IsWindow(hwnd):
+        return {"ok": False, "reason": "Target window closed", "hwnd": int(hwnd)}
+    if u.IsHungAppWindow(hwnd):
+        return {"ok": False, "reason": "Target window is not responding", "hwnd": int(hwnd)}
+
+    def focused_child():
+        info = GUIThreadInfo()
+        info.cbSize = ctypes.sizeof(info)
+        if u.GetGUIThreadInfo(target, ctypes.byref(info)):
+            child = info.hwndFocus
+            if child and (child == hwnd or u.IsChild(hwnd, child)):
+                return child
+        return None
+
+    def confirmed():
+        return u.GetForegroundWindow() == hwnd and not u.IsIconic(hwnd) and bool(focused_child())
+
+    # Remember the editor/terminal input child before activation, rather than
+    # unconditionally moving keyboard focus to its top-level frame.
+    child = focused_child()
+    if u.IsIconic(hwnd):
+        u.ShowWindowAsync(hwnd, 9)  # SW_RESTORE
+    accepted = bool(u.SetForegroundWindow(hwnd))
+    for _ in range(5):
+        if confirmed():
+            return {"ok": True, "hwnd": int(hwnd), "method": "SetForegroundWindow", "keyboardFocus": True}
+        sleep(0.04)
+
+    # A broker worker is not a GUI thread. Explicitly create its message queue
+    # before attaching, and attach BOTH the foreground and destination threads.
+    message = wintypes.MSG()
+    u.PeekMessageW(ctypes.byref(message), None, 0, 0, 0)  # PM_NOREMOVE
+    foreground = u.GetForegroundWindow()
+    other = u.GetWindowThreadProcessId(foreground, None) if foreground else 0
+    attached, failed = [], []
+    try:
+        for thread in dict.fromkeys((other, target)):
+            if not thread or thread == current:
+                continue
+            if u.AttachThreadInput(current, thread, True):
+                attached.append(thread)
+            else:
+                failed.append(thread)
+        if u.IsWindow(hwnd):
+            u.BringWindowToTop(hwnd)
+            u.SetForegroundWindow(hwnd)
+            if target == current or target in attached:
+                u.SetActiveWindow(hwnd)
+                # Prefer the application's current focus after activation, then
+                # its previously focused child if it still belongs to this frame.
+                focus = focused_child()
+                if not focus and child and u.IsWindow(child) and u.IsChild(hwnd, child):
+                    focus = child
+                u.SetFocus(focus or hwnd)
+    finally:
+        for thread in reversed(attached):
+            u.AttachThreadInput(current, thread, False)
+    for _ in range(5):
+        if confirmed():
+            return {"ok": True, "hwnd": int(hwnd), "method": "AttachThreadInput", "keyboardFocus": True}
+        sleep(0.04)
+    return {
+        "ok": False,
+        "reason": "Windows denied foreground or keyboard focus",
+        "hwnd": int(hwnd),
+        "apiAccepted": accepted,
+        "foreground": int(u.GetForegroundWindow() or 0),
+        "keyboardFocus": bool(focused_child()),
+        "attachmentFailures": failed,
+    }

ocdeck/hardware_check.py

@@ -0,0 +1,66 @@
+"""Manual six-key diagnostic with actual USB events, isolated from the broker."""
+
+import json
+import queue
+import time
+from PIL import Image, ImageDraw, ImageFont
+from .broker import InstanceLock
+from .common import home, read_json, atomic_json
+from .device import enumerate_devices, device_types, elgato_running, WheelTransport
+
+
+def run():
+    from StreamDeck.ImageHelpers import PILHelper
+
+    root = home()
+    root.mkdir(parents=True, exist_ok=True)
+    with InstanceLock(root):
+        if elgato_running():
+            raise RuntimeError("Quit Elgato Stream Deck, then run ocdeck doctor")
+        devices = enumerate_devices()
+        serial = read_json(root / "config.json", {}).get("serial")
+        if serial:
+            devices = [d for d in devices if d.get("serial_number") == serial]
+        if len(devices) != 1:
+            raise RuntimeError("Expected one deck; select a serial in config.json")
+        deck = device_types()[devices[0]["product_id"]](WheelTransport(devices[0]))
+        count = deck.key_count()
+        presses = queue.Queue()
+        observed = []
+        try:
+            deck.open()
+            deck.set_brightness(45)
+            for key in range(count):
+                im = Image.new("RGB", (80, 80), "#123b5c")
+                ImageDraw.Draw(im).text(
+                    (40, 40), str(key + 1), font=ImageFont.load_default(size=36), fill="white", anchor="mm"
+                )
+                deck.set_key_image(key, PILHelper.to_native_key_format(deck, im))
+            deck.set_key_callback(lambda d, k, pressed: presses.put(k + 1) if pressed else None)
+            print(f"{count} numbered images submitted. Confirm physical key order.")
+            print(f"Press physical keys 1 through {count} in order within 60 seconds.")
+            deadline = time.monotonic() + 60
+            while len(observed) < count and time.monotonic() < deadline:
+                try:
+                    key = presses.get(timeout=min(1, max(0.01, deadline - time.monotonic())))
+                    observed.append(key)
+                    print(f"Physical key-down received: {key}", flush=True)
+                except queue.Empty:
+                    pass
+            result = {
+                "time": time.time(),
+                "serial": devices[0].get("serial_number"),
+                "physicalKeys": observed,
+                "keyOrderPass": observed == list(range(1, count + 1)),
+                "displayVisuallyConfirmed": False,
+                "note": "Display appearance requires human confirmation; API writes are not camera evidence.",
+            }
+            atomic_json(root / "hardware-check.json", result)
+            print(json.dumps(result, indent=2))
+        finally:
+            try:
+                blank = PILHelper.to_native_key_format(deck, Image.new("RGB", (80, 80), "black"))
+                for key in range(count):
+                    deck.set_key_image(key, blank)
+            finally:
+                deck.close()

ocdeck/harness.py

@@ -0,0 +1,203 @@
+"""Managed hook-harness supervisor. The existing broker and identity rules are unchanged."""
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from .common import home, identity, atomic_json, read_json, request
+
+PROFILES = {
+    "codex": "codex",
+    "claude": "claude",
+    "copilot-cli": "copilot",
+    "copilot-vscode": "code",
+    "gemini": "gemini",
+    "cursor": "agent",
+}
+SOURCE = Path(__file__).resolve().parent.parent
+if not (SOURCE / "plugins/harnesses/install.mjs").is_file():
+    SOURCE = Path(__file__).resolve().parent / "runtime"
+
+
+def install(profile, project, remove=False, dry_run=False):
+    node = shutil.which("node")
+    if not node:
+        raise RuntimeError("Node.js 20+ must be on PATH for hook adapters")
+    result = subprocess.call(
+        [
+            node,
+            str(SOURCE / "plugins/harnesses/install.mjs"),
+            "--cli",
+            profile,
+            str(Path(project).resolve()),
+            *(["--remove"] if remove else []),
+            *(["--dry-run"] if dry_run else []),
+        ]
+    )
+    if result == 0 and not dry_run:
+        projects = read_json(home() / "projects.json", []) or []
+        resolved = str(Path(project).resolve())
+        if resolved not in projects:
+            projects.append(resolved)
+            atomic_json(home() / "projects.json", projects)
+    return result
+
+
+def launch(profile, args, executable=None, current_window=False):
+    executable = shutil.which(executable or PROFILES[profile])
+    if not executable:
+        raise RuntimeError("Harness executable not found; install it or pass --executable")
+    if not shutil.which("node"):
+        raise RuntimeError("Node.js 20+ must be on PATH")
+    key = str(uuid.uuid4())
+    spec = {
+        "id": key,
+        "profile": profile,
+        "executable": executable,
+        "cwd": os.getcwd(),
+        "args": args,
+        "windowToken": "" if current_window or os.name != "nt" else f"AgentDeck [{key}]",
+    }
+    if os.name != "nt" or current_window:
+        return worker(spec)
+    wt = shutil.which("wt.exe")
+    if not wt:
+        raise RuntimeError("Windows Terminal required; use --current-window for status-only testing")
+    file = home() / "launches" / (key + ".harness.json")
+    atomic_json(file, spec)
+    try:
+        terminal_title = spec["windowToken"] + (" launcher" if profile == "copilot-vscode" else "")
+        subprocess.Popen(
+            [
+                wt,
+                "-w",
+                key,
+                "new-tab",
+                "--title",
+                terminal_title,
+                "--suppressApplicationTitle",
+                "--inheritEnvironment",
+                sys.executable,
+                "-m",
+                "ocdeck",
+                "harness-worker",
+                str(file),
+            ]
+        )
+    except Exception:
+        file.unlink(missing_ok=True)
+        raise
+    return 0
+
+
+def worker(spec):
+    spec_file = None
+    if not isinstance(spec, dict):
+        spec_file = Path(spec)
+        spec = read_json(spec_file)
+    if not isinstance(spec, dict):
+        raise ValueError("Invalid managed launch specification")
+    node = shutil.which("node")
+    if not node:
+        raise RuntimeError("Install Node.js 20+ and restart the terminal")
+    root = home().resolve()
+    directory = root / "launches" / (spec["id"] + ".hooks")
+    directory.mkdir(parents=True, mode=0o700)
+    binding, descriptor = directory / "binding.json", directory / "hook.json"
+    reg = {
+        "id": spec["id"],
+        "process": identity(),
+        "windowToken": spec["windowToken"],
+        "harness": spec["profile"],
+        "label": spec["profile"] + ":" + Path(spec["cwd"]).name,
+        "managed": True,
+    }
+    atomic_json(binding, reg)
+    env = dict(os.environ, OCDECK_HOME=str(root), AGENTDECK_HOOK_BINDING=str(descriptor))
+    # Do not let nested OpenCode instances claim an unrelated managed launch.
+    env.pop("OCDECK_BINDING", None)
+    bridge = child = None
+    try:
+        bridge = subprocess.Popen(
+            [
+                node,
+                str(SOURCE / "plugins/harnesses/bridge.mjs"),
+                "--worker",
+                spec["profile"],
+                str(binding),
+                str(descriptor),
+            ],
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+        )
+        deadline = time.monotonic() + 5
+        while not descriptor.exists():
+            if bridge.poll() is not None or time.monotonic() > deadline:
+                raise RuntimeError("Hook bridge did not start")
+            time.sleep(0.025)
+        command = [spec["executable"], *spec["args"]]
+        if spec["profile"] == "copilot-vscode":
+            # A separate VS Code application instance is required for environment inheritance.
+            # Unique data avoids silently reusing an existing editor with a stale binding.
+            editor_key = spec["id"]
+            editor_data = root / "editors" / editor_key
+            if spec["windowToken"]:
+                atomic_json(editor_data / "User/settings.json", {"window.title": spec["windowToken"]})
+            command += ["--new-window", "--wait", "--user-data-dir", str(editor_data), spec["cwd"]]
+        # Native executables use CreateProcess argv quoting directly. Legacy
+        # PowerShell argument binding drops embedded quotes on Windows.
+        if os.name == "nt" and Path(command[0]).suffix.lower() in (".bat", ".cmd", ".ps1"):
+            launch_file = directory / "command.json"
+            atomic_json(launch_file, {"executable": command[0], "args": command[1:], "cwd": spec["cwd"]})
+            command = [
+                "powershell.exe",
+                "-NoLogo",
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                str(SOURCE / "scripts/Run-OpenCode.ps1"),
+                "-LaunchFile",
+                str(launch_file),
+            ]
+        child = subprocess.Popen(command, cwd=spec["cwd"], env=env)
+        warned = False
+        while child.poll() is None:
+            if bridge.poll() is not None and not warned:
+                print(
+                    "AgentStreamDeck bridge exited; status will become unknown. Restart this launch to reconnect.",
+                    file=sys.stderr,
+                )
+                warned = True
+            try:
+                time.sleep(0.2)
+            except KeyboardInterrupt:
+                pass  # Child shares console and receives Ctrl+C; keep watching until it exits.
+        return child.returncode
+    finally:
+        if child and child.poll() is None:
+            child.terminate()
+            try:
+                child.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                child.kill()
+                child.wait()
+        if bridge:
+            if bridge.stdin:
+                bridge.stdin.close()
+            try:
+                bridge.wait(timeout=4)
+            except subprocess.TimeoutExpired:
+                bridge.kill()
+                bridge.wait()
+        try:
+            request("DELETE", "/v1/instances/" + reg["id"], root=root)
+        except Exception:
+            pass
+        shutil.rmtree(directory, ignore_errors=True)
+        if spec_file:
+            spec_file.unlink(missing_ok=True)