@typecad/framework-zephyr 1.0.0-alpha.15 → 1.0.0-alpha.18

package/dist/toolchain/index.js

@@ -10,22 +10,24 @@
 // a SDK root is discovered. See west-discover.ts / west-spawn.ts.
 //
 // The board target is carried via frameworkData.buildTarget (populated as
-// ToolchainOptions.buildTarget by the cuttlefish CLI), defaulting to the
+// ToolchainOptions.buildTarget by the typecad-hal CLI), defaulting to the
 // framework's canonical MVP target (xiao_ble).
 //
 // Mirrors framework-esp32/src/toolchain/index.ts structure: projectRoot derived
 // from outputDir, prepare is a no-op (scaffold happens in compile when the
 // target is known), GCC errors parsed via the shared parseCompileErrors helper.
 // ---------------------------------------------------------------------------
-import { spawnSync } from 'node:child_process';
-import { basename, dirname, join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { connect as netConnect } from 'node:net';
+import { basename, delimiter, dirname, join } from 'node:path';
 import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
 import { parseZephyrDts, asBuiltJson } from '../as-built.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
-import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
+import { writeDebugConfig, resolveDebugLocations, debugArtifactsNeedRewrite, DEBUG_SERVER_PORT, DEBUG_SERVER_TCL_PORT } from './debug-config.js';
+import { readRunnersFacts } from './runners.js';
 import { bossacTouchReset } from './bossac-touch.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
@@ -255,12 +257,12 @@ function targetFromOptions(o) {
     const fcTarget = o.frameworkConfig?.target;
     const board = o.buildTarget ?? fcTarget;
     if (!board) {
-        throw new Error('No build target: set board: in cuttlefish.config.ts (or frameworkData.buildTarget for custom-board projects).');
+        throw new Error('No build target: set board: in typecad-hal.config.ts (or frameworkData.buildTarget for custom-board projects).');
     }
     return board;
 }
 /**
- * Derive the Zephyr project root from the cuttlefish-emitted source path.
+ * Derive the Zephyr project root from the typecad-hal-emitted source path.
  *
  * Cuttlefish emits `src/main.cpp` under the output dir. The CLI passes
  * `sourcePath` = full path to `main.cpp` and `outputDir` = its parent (`src/`).
@@ -280,6 +282,23 @@ export function projectRootFromOptions(o) {
  */
 const BUILD_TIMEOUT_MS = 600_000;
 const FLASH_TIMEOUT_MS = 120_000;
+/**
+ * The board a cached build dir was configured for (CMakeCache.txt's
+ * BOARD:STRING — the exact value passed to `west build -b`), or undefined
+ * when no cache exists. compile() compares it against the requested board
+ * and nukes the dir on mismatch: `west build`'s --pristine=auto covers
+ * cmake/config churn, NOT a board switch — west aborts with "refusing to
+ * proceed without --force", and cuttlefish doesn't forward that flag.
+ */
+export function cachedBuildBoard(buildDir) {
+    try {
+        return readFileSync(join(buildDir, 'CMakeCache.txt'), 'utf-8')
+            .match(/^BOARD:STRING=(.+)$/m)?.[1]?.trim() || undefined;
+    }
+    catch {
+        return undefined; // no build dir / unreadable cache — treat as fresh
+    }
+}
 export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     const probe = zc?.probe;
     const runner = zc?.runner;
@@ -287,7 +306,7 @@ export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     if (probe && runner) {
         return {
             ok: false,
-            error: `cuttlefish.config.ts sets both zephyr.probe ('${probe}') and zephyr.runner ('${runner}'). ` +
+            error: `typecad-hal.config.ts sets both zephyr.probe ('${probe}') and zephyr.runner ('${runner}'). ` +
                 `They are two ways to choose the probe method — remove one.`,
         };
     }
@@ -322,14 +341,31 @@ export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     }
     return { ok: true, runner, args: userArgs };
 }
-/**
- * Run an openocd session against the board's probe config — the shared
- * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
- * call sites in upload()). The config is the probe method's verbatim
- * debugCfg from the board catalog (the same lines `west debug` uses);
- * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
- * success, undefined when skipped or failed (best-effort by design).
- */
+export function resolveSessionOpenOcd(env = process.env, sdkInstallDir) {
+    const exeName = process.platform === 'win32' ? 'openocd.exe' : 'openocd';
+    if (env.OPENOCD && existsSync(env.OPENOCD)) {
+        return { exe: env.OPENOCD, searchDirs: [] };
+    }
+    const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || sdkInstallDir;
+    if (sdkRoot) {
+        const exe = join(sdkRoot, 'hosttools', 'openocd', 'bin', exeName);
+        if (existsSync(exe)) {
+            const searchDirs = [
+                join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts'),
+                join(sdkRoot, 'hosttools', 'openocd', 'scripts'),
+            ].filter((d) => existsSync(d));
+            return { exe, searchDirs };
+        }
+    }
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, exeName);
+        if (existsSync(candidate))
+            return { exe: candidate, searchDirs: [] };
+    }
+    return undefined;
+}
 function openocdProbeSession(buildDir, zc, chip, commands) {
     // Config resolution — two sources, in order:
     //   1. The named probe method's verbatim debugCfg from the board catalog
@@ -360,21 +396,15 @@ function openocdProbeSession(buildDir, zc, chip, commands) {
             .map((a) => a.slice('--cmd-pre-init='.length)),
     ];
     const install = discoverWest();
-    const sdkRoot = process.env.ZEPHYR_SDK_INSTALL_DIR || install?.sdkInstallDir;
-    if (!sdkRoot)
+    const sessionOpenOcd = resolveSessionOpenOcd(process.env, install?.sdkInstallDir);
+    if (!sessionOpenOcd)
         return undefined;
-    const openocdExe = join(sdkRoot, 'hosttools', 'openocd', 'bin', process.platform === 'win32' ? 'openocd.exe' : 'openocd');
-    if (!existsSync(openocdExe))
-        return undefined;
-    // Script search path: the SDK layouts differ across versions — prefer the
-    // share/ form west's own runner uses, fall back to the scripts/ form.
-    const shareScripts = join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts');
-    const binScripts = join(sdkRoot, 'hosttools', 'openocd', 'scripts');
-    const searchDir = existsSync(shareScripts) ? shareScripts : binScripts;
+    const openocdExe = sessionOpenOcd.exe;
+    const searchArgs = sessionOpenOcd.searchDirs.flatMap((d) => ['-s', d]);
     let cfgArgs;
     let sessionCfg;
     if (cfgLines && cfgLines.length > 0) {
-        sessionCfg = join(buildDir, 'cuttlefish-probe.cfg');
+        sessionCfg = join(buildDir, 'typecad-hal-probe.cfg');
     }
     else {
         // The board target's qualifier ('blackpill_f411ce/stm32f411xe' →
@@ -409,7 +439,7 @@ function openocdProbeSession(buildDir, zc, chip, commands) {
             cfgArgs = ['-f', sessionCfg];
         }
         const res = spawnSync(openocdExe, [
-            '-s', searchDir, ...cfgArgs,
+            ...searchArgs, ...cfgArgs,
             // Pre-init TCL AFTER the cfg (overrides its reset_config) and BEFORE
             // init — the same position west gives --cmd-pre-init.
             ...preInit.map((c) => ['-c', c]).flat(),
@@ -503,6 +533,18 @@ function isUf2DriveVanishRace(output) {
         && /WinError 433/.test(output)
         && /copymode/.test(output);
 }
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export function isTargetSwdFailure(output) {
+    return /unable to connect to the target|timed out while waiting for target halted|TARGET: \S+ - Not halted/.test(output);
+}
 /**
  * Cleanse the `west flash` output shown to the user.
  *
@@ -691,7 +733,7 @@ export const Toolchain = {
             // Custom-board generation: an MCU-only target (no board package) has no
             // upstream Zephyr board — generate one under boards/typecad/<name>/ from
             // the chip's silicon data. Opt-in via `zephyr.customBoard: true` in
-            // cuttlefish.config.ts; the board takes its name from the build target.
+            // typecad-hal.config.ts; the board takes its name from the build target.
             // Idempotent — regenerated on every compile, before the overlay pass.
             if (zc?.customBoard === true) {
                 const generated = generateCustomBoard(projectRoot, chip, board.split('/')[0]);
@@ -868,10 +910,15 @@ export const Toolchain = {
         // .ninja_deps, after which every ninja run fails with `dependency cycle`.
         // Plain source edits never reconfigure CMake, so they cannot trigger it —
         // and the retry after the spawn below self-heals any path that still does.
-        // Board switches need no nuke here: `west build` is --pristine=auto by
-        // default and recreates the dir itself when -b <board> mismatches the
-        // cached board.
-        if (configChanged) {
+        // Board switches DO need a nuke: `west build`'s --pristine=auto covers
+        // cmake/config churn, not a -b <board> mismatch — west aborts with
+        // "refusing to proceed without --force" and cuttlefish doesn't forward
+        // that flag, so the user would be stuck deleting the dir by hand. The
+        // cache names the board it was configured for (BOARD:STRING); detect the
+        // mismatch and apply west's own suggested remedy automatically.
+        const cachedBoard = cachedBuildBoard(buildDir);
+        const boardChanged = Boolean(cachedBoard && cachedBoard !== board);
+        if (configChanged || boardChanged) {
             try {
                 rmSync(buildDir, { recursive: true, force: true });
             }
@@ -892,7 +939,7 @@ export const Toolchain = {
             }
         }
         catch { /* no overlay — let Zephyr auto-detect or build without one */ }
-        // Append user cmake args from cuttlefish.config.ts zephyr.cmakeArgs.
+        // Append user cmake args from typecad-hal.config.ts zephyr.cmakeArgs.
         const userCmakeArgs = zc?.cmakeArgs;
         if (userCmakeArgs && userCmakeArgs.length > 0) {
             if (!buildArgs.includes('--'))
@@ -918,36 +965,39 @@ export const Toolchain = {
         const stdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
         const stderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
         const output = stdout + stderr + (pristineRetry
-            ? '\n[cuttlefish] dependency cycle detected in the cached build dir — retried with a pristine build'
+            ? '\n[typecad-hal] dependency cycle detected in the cached build dir — retried with a pristine build'
             : '');
         // Prefix the build log with how west was resolved, for transparency.
         const header = `Using west via ${inv.install.source}` +
             (inv.install.zephyrBase ? ` (ZEPHYR_BASE=${inv.install.zephyrBase})` : '') + '\n';
-        // After a successful build in gdb mode (--debug on a probe-capable target),
-        // write the VS Code launch.json + tasks.json + gdb-script artifacts so F5
-        // attaches GDB to the chip's debug probe. Non-fatal on failure — a missing
-        // artifact doesn't block the build. Mirrors the deleted framework-esp32
-        // toolchain compile() debug-config wiring.
-        if (result.status === 0 && isGdbDebug) {
+        // After a successful build on a gdb-capable board, keep the VS Code debug
+        // artifacts current: always under --debug, or on a plain build when they
+        // need it (still in create-time starter shape, an outDir rename moved the
+        // app root, or a pre-west self-managed-server entry). Non-fatal on
+        // failure — a missing artifact doesn't block the build.
+        if (result.status === 0 && debugMode === 'gdb') {
             try {
                 const { workspaceRoot, appRel } = resolveDebugLocations(projectRoot);
-                writeDebugConfig({
-                    projectRoot,
-                    workspaceRoot,
-                    appRel,
-                    target: board,
-                    buildDir,
-                    sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
-                });
+                if (isGdbDebug
+                    || debugArtifactsNeedRewrite(workspaceRoot, appRel, readRunnersFacts(buildDir)?.gdb?.replace(/\\/g, '/'))) {
+                    writeDebugConfig({
+                        projectRoot,
+                        workspaceRoot,
+                        appRel,
+                        target: board,
+                        buildDir,
+                        sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
+                    });
+                }
             }
             catch (e) {
-                console.warn(`[cuttlefish] gdb debug config generation failed: ${e.message}`);
+                console.warn(`[typecad-hal] gdb debug config generation failed: ${e.message}`);
             }
         }
         // As-built snapshot: after a successful build, the resolved devicetree
         // at <buildDir>/zephyr/zephyr.dts carries the board's pinctrl labels —
         // the STABLE name grammar, immune to vendor macro churn. Harvest its
-        // routes into .cuttlefish/as-built.json; the next build's board-module
+        // routes into .typecad-hal/as-built.json; the next build's board-module
         // generation merges them per-pin over the catalog harvest (build wins,
         // silently when they agree). One-build freshness lag on first setup,
         // self-maintaining after. Best-effort — a missing/unparseable artifact
@@ -959,14 +1009,14 @@ export const Toolchain = {
                 const facts = parseZephyrDts(dtsText);
                 const total = facts.adc.length + facts.pwm.length + facts.dac.length;
                 if (total > 0) {
-                    // Write beside the project's board module — the .cuttlefish dir the
+                    // Write beside the project's board module — the .typecad-hal dir the
                     // config loader reads from, discovered by walking up to the
                     // generated board.json (the scaffold root and the config root are
                     // different dirs in the standard layout: src/out vs project root).
-                    let cfDir = join(projectRoot, '.cuttlefish');
+                    let cfDir = join(projectRoot, '.typecad-hal');
                     for (let dir = projectRoot;; dir = dirname(dir)) {
-                        if (existsSync(join(dir, '.cuttlefish', 'board.json'))) {
-                            cfDir = join(dir, '.cuttlefish');
+                        if (existsSync(join(dir, '.typecad-hal', 'board.json'))) {
+                            cfDir = join(dir, '.typecad-hal');
                             break;
                         }
                         const parent = dirname(dir);
@@ -995,6 +1045,22 @@ export const Toolchain = {
         if (!probe.ok) {
             return { success: false, output: `-- west flash: ${probe.error}` };
         }
+        // Flashing over a probe needs it EXCLUSIVE: a debug server still bound to
+        // the gdb port (live session or an orphan whose wrapper died — a VS Code
+        // window reload kills task terminals without killing their children on
+        // Windows) makes openocd fail with LIBUSB_ERROR_ACCESS before any retry
+        // logic can help. Reclaim it up front — it is ours by convention.
+        {
+            const holder = portOwnerPid(DEBUG_SERVER_PORT);
+            if (holder !== undefined && holder !== process.pid) {
+                console.log(`-- west flash: stopping debug server (pid ${holder}) — flashing needs exclusive probe access`);
+                killPidTree(holder);
+                try {
+                    rmSync(join(projectRoot, '.typecad-hal', 'debug-server.pid'), { force: true });
+                }
+                catch { /* already gone */ }
+            }
+        }
         // BOSSA bootloader boards with touch-reset data: open the app's console
         // port at 1200 baud (the firmware's USB shim reboots into the
         // bootloader), wait for the bootloader identity, and flash THAT port.
@@ -1012,7 +1078,7 @@ export const Toolchain = {
         if (uploadRequiresPort(flashRunner) && !flashPort) {
             return {
                 success: false,
-                output: `-- upload requires a port for ${flashRunner} flashing. Set --port <port> on the command line (or the CUTTLEFISH_PORT env var).`,
+                output: `-- upload requires a port for ${flashRunner} flashing. Set --port <port> on the command line (or the TYPECAD_HAL_PORT env var).`,
             };
         }
         if (flashRunner === 'bossac' && flashPort && chip.usb?.touchReset) {
@@ -1112,6 +1178,12 @@ export const Toolchain = {
                 ]);
                 if (revived)
                     flashNotes.push(revived);
+                // Known SWD-failure signatures get a recovery pointer — a board that
+                // ignores SWD until power-cycled (low-power state, lockup, a wedged
+                // probe) otherwise reads as a toolchain bug.
+                if (isTargetSwdFailure(raw)) {
+                    flashNotes.push('-- target ignored SWD — if a retry fails too: power-cycle the board, replug the probe, or skip SWD entirely (hold BOOT0, tap reset, re-run with --probe dfu)');
+                }
             }
         }
         else {
@@ -1143,6 +1215,14 @@ export const Toolchain = {
         // python we spawn resolves pyserial from the same venv). Falls back to the
         // process env when no install is discovered.
         const env = install ? buildEnv(install) : process.env;
+        // Post-flash re-enumeration: the chip resets when `--upload` finishes, the
+        // OS tears the serial device object down and re-creates it, and miniterm's
+        // single open can land inside that window (a FileNotFoundError even though
+        // the board never unplugged). Wait for the port to (re)appear first.
+        if (!waitForSerialPort(py, env, projectRootFromOptions(o), o.port)) {
+            process.exitCode = 1;
+            return;
+        }
         spawnSync(py, ['-m', 'serial.tools.miniterm', o.port, String(baud)], {
             cwd: projectRootFromOptions(o),
             env,
@@ -1177,4 +1257,301 @@ export const Toolchain = {
         });
         spawnSync(inv.command, inv.args, inv.options);
     },
+    debugServer(o, action) {
+        const projectRoot = projectRootFromOptions(o);
+        const buildDir = join(projectRoot, 'build');
+        const pidFile = join(projectRoot, '.typecad-hal', 'debug-server.pid');
+        if (action === 'stop') {
+            stopDebugServer(pidFile);
+            return;
+        }
+        // start: wrap `west debugserver` as a long-running foreground process (the
+        // VS Code background task owns this process; postDebugTask runs `stop`).
+        if (!existsSync(join(buildDir, 'zephyr', 'runners.yaml'))) {
+            console.error(`! No build at ${buildDir} — run 'npm run compile' (or F5's preLaunchTask) first.`);
+            process.exitCode = 1;
+            return;
+        }
+        const stale = readStaleServerPid(pidFile);
+        if (stale !== undefined) {
+            // Already running (pid alive): just re-emit the ready marker so the
+            // task's problem matcher completes immediately.
+            console.log(`[typecad-hal] west debugserver already running (pid ${stale})`);
+            console.log(`TYPECAD_HAL: debug server ready on ${DEBUG_SERVER_PORT}`);
+            return;
+        }
+        try {
+            rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+        // A wrapper/west that died without cleanup can leave openocd bound to
+        // the gdb port with a stale pidfile — reclaim it or the new server
+        // cannot bind (and gdb would attach to the orphan).
+        const orphan = portOwnerPid(DEBUG_SERVER_PORT);
+        if (orphan !== undefined && orphan !== process.pid) {
+            console.log(`[typecad-hal] reclaiming orphaned debug server on :${DEBUG_SERVER_PORT} (pid ${orphan})`);
+            killPidTree(orphan);
+        }
+        // Runner + quirk parity with flash (resolveProbeMethod, same as `west
+        // debug`): an explicit zephyr.probe selects the runner; either way, an
+        // srst-based openocd cfg behind an unwired NRST (the probeRunnerQuirks
+        // condition, read from the board's own method data) makes `reset init`
+        // time out — the IDE's post-attach reset would hang the session. Apply
+        // the core-reset override server-side unless the config's runnerArgs
+        // already carry it (the create flow bakes it in).
+        const board = targetFromOptions(o);
+        const chip = chipForBuild(projectRoot, board);
+        const zc = o.zephyrConfig;
+        const probe = resolveProbeMethod(zc, chip, 'debug');
+        // The runner west will actually drive: the explicit choice, else the
+        // board's declared debug-runner default from the build's runners.yaml.
+        const runner = ((probe.ok && probe.runner) || undefined)
+            ?? readRunnersFacts(buildDir)?.debugRunner;
+        const isOcd = runner === undefined || runner === 'openocd' || runner.startsWith('openocd');
+        if (!isOcd) {
+            console.warn(`! debug-server: the IDE wiring (ready marker, quirk args) targets the ` +
+                `openocd runner; this build's debug runner is '${runner}'. Starting it plain — ` +
+                `the F5 session may not connect.`);
+        }
+        const serverArgs = ['debugserver', '-d', buildDir];
+        if (probe.ok) {
+            if (probe.runner)
+                serverArgs.push('--runner', probe.runner);
+            serverArgs.push(...probe.args);
+        }
+        if (isOcd) {
+            serverArgs.push('--gdb-port', String(DEBUG_SERVER_PORT), 
+            // Pinned so the readiness poll below has a deterministic port.
+            '--tcl-port', String(DEBUG_SERVER_TCL_PORT), 
+            // The board's own openocd.cfg may declare gdb-attach/gdb-detach
+            // events (reset-on-attach for standalone sessions). Under an
+            // IDE-managed session a stop event mid-initialization aborts
+            // debugger setup, so neutralize them: west's --cmd-pre-init lands
+            // AFTER the cfg files in the openocd command line, so these win.
+            '--cmd-pre-init', '$_TARGETNAME configure -event gdb-attach {}', '--cmd-pre-init', '$_TARGETNAME configure -event gdb-detach {}');
+            const method = zc?.probe
+                ? chip.probeMethods?.find((m) => m.id === zc?.probe)
+                : chip.probeMethods?.find((m) => m.debug !== false);
+            const cfg = method?.debugCfg ?? [];
+            const srst = cfg.some((l) => /reset_config\s+srst/.test(l));
+            const connectAssert = cfg.some((l) => /connect_assert_srst/.test(l));
+            if (method?.runner === 'openocd' && srst && !connectAssert
+                && !(probe.ok && probe.args.includes('--cmd-pre-init=reset_config none'))) {
+                serverArgs.push('--cmd-pre-init', 'reset_config none');
+            }
+        }
+        const inv = westSpawn(serverArgs, { cwd: projectRoot });
+        const child = spawn(inv.command, inv.args, {
+            ...inv.options,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Own process group on POSIX so `stop` can signal the whole tree.
+            ...(process.platform !== 'win32' ? { detached: true } : {}),
+        });
+        // @types/node 26 types ChildProcess's on/once through the internal
+        // InternalEventEmitter base. When `tsc -b` rechecks this package in the
+        // same solution pass that rebuilds its project references, that
+        // inheritance can fail to surface and the spawned child's type loses
+        // .on/.once (TS2339) — while stream types, which COPY the event
+        // signatures, keep working. Subscribe through a structural copy of the
+        // one signature this file needs: the copy-don't-inherit prescription
+        // @types/node itself applies to multi-level emitter classes. The `unknown`
+        // hop keeps the cast legal in both resolution states.
+        const childExit = child;
+        mkdirSync(join(projectRoot, '.typecad-hal'), { recursive: true });
+        writeFileSync(pidFile, String(child.pid), 'utf-8');
+        console.log(`[typecad-hal] starting west debugserver (gdb on localhost:${DEBUG_SERVER_PORT})`);
+        // A reader that goes away (closed task terminal, piped head) must not
+        // take the server down with an EPIPE.
+        process.stdout?.on?.('error', () => { });
+        process.stderr?.on?.('error', () => { });
+        child.stdout?.on('data', (d) => process.stdout.write(d));
+        child.stderr?.on('data', (d) => process.stderr.write(d));
+        // Ready = the TCL port accepts connections. NOT the gdb port: openocd's
+        // gdb server takes ONE client, so a TCP probe there both logs
+        // "attempted 'gdb' connection rejected" and can race the real gdb
+        // connection for the slot. The tcl listener opens at the END of openocd
+        // init (after the gdb listener and the startup halt) — a truer signal —
+        // and probes there are inert.
+        const deadline = Date.now() + DEBUG_SERVER_START_TIMEOUT_MS;
+        const poll = () => {
+            const sock = netConnect(DEBUG_SERVER_TCL_PORT, '127.0.0.1');
+            sock.once('connect', () => {
+                sock.destroy();
+                console.log(`TYPECAD_HAL: debug server ready on ${DEBUG_SERVER_PORT}`);
+            });
+            sock.once('error', () => {
+                sock.destroy();
+                if (child.exitCode !== null)
+                    return; // server died — exit handler reports
+                if (Date.now() > deadline) {
+                    console.error(`! west debugserver did not open :${DEBUG_SERVER_TCL_PORT} within `
+                        + `${DEBUG_SERVER_START_TIMEOUT_MS / 1000}s — see its output above.`);
+                    stopDebugServer(pidFile);
+                    process.exitCode = 1;
+                    return;
+                }
+                setTimeout(poll, 250);
+            });
+        };
+        poll();
+        childExit.on('exit', (code) => {
+            try {
+                rmSync(pidFile, { force: true });
+            }
+            catch { /* already gone */ }
+            // Exit before ready: surface as a task failure (the debugger never
+            // connects and VS Code reports the background task's non-zero exit).
+            if (code !== null && code !== 0)
+                process.exitCode = code;
+        });
+        const forwardSignal = () => {
+            stopDebugServer(pidFile);
+            childExit.once('exit', () => process.exit(0));
+            setTimeout(() => process.exit(0), 1500).unref();
+        };
+        process.on('SIGINT', forwardSignal);
+        process.on('SIGTERM', forwardSignal);
+    },
 };
+/** How long `debug-server start` waits for the gdb port before failing. */
+const DEBUG_SERVER_START_TIMEOUT_MS = 45_000;
+/**
+ * Read the pidfile and return the pid when that process is still alive,
+ * undefined otherwise (no file, dead pid, or unparseable). Best-effort.
+ */
+function readStaleServerPid(pidFile) {
+    try {
+        const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+        if (!Number.isInteger(pid))
+            return undefined;
+        process.kill(pid, 0); // throws ESRCH when dead
+        return pid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The pid of whatever process is LISTENING on the gdb port — the recovery
+ * path for orphaned servers (the wrapper and west can die while openocd
+ * survives, e.g. a killed task terminal; the pidfile is then stale but the
+ * port stays bound and the next session would attach to the orphan).
+ * Best-effort: netstat on Windows, lsof on POSIX; undefined when the port is
+ * free or the platform tool is unavailable.
+ */
+function portOwnerPid(port) {
+    try {
+        if (process.platform === 'win32') {
+            const out = spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf-8' });
+            if (out.status !== 0)
+                return undefined;
+            for (const line of (out.stdout ?? '').split(/\r?\n/)) {
+                const cols = line.trim().split(/\s+/);
+                if (cols.length >= 5 && cols[3] === 'LISTENING'
+                    && cols[1].endsWith(`:${port}`)) {
+                    const pid = Number.parseInt(cols[4], 10);
+                    if (Number.isInteger(pid))
+                        return pid;
+                }
+            }
+            return undefined;
+        }
+        const out = spawnSync('lsof', ['-ti', `tcp:${port}`], { encoding: 'utf-8' });
+        if (out.status !== 0 || !out.stdout?.trim())
+            return undefined;
+        const pid = Number.parseInt(out.stdout.trim().split(/\s+/)[0], 10);
+        return Number.isInteger(pid) ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Kill a pid tree (Windows: taskkill /T; POSIX: the process group). */
+function killPidTree(pid) {
+    if (process.platform === 'win32') {
+        // /T: the whole tree (the pid may be the micromamba/west wrapper; openocd
+        // is its grandchild). /F: force — the server has no stdin to close.
+        spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf-8' });
+    }
+    else {
+        try {
+            process.kill(-pid, 'SIGTERM'); // the detached process group
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+        }
+    }
+}
+/** Kill the debug server tree (micromamba/west → openocd) and drop the pidfile.
+ *  Falls back to the gdb-port owner when the recorded pid is already dead —
+ *  that orphan would otherwise serve stale sessions forever. */
+function stopDebugServer(pidFile) {
+    const pid = readStaleServerPid(pidFile) ?? portOwnerPid(DEBUG_SERVER_PORT);
+    if (pid === undefined) {
+        try {
+            rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+        console.log('[typecad-hal] debug server not running');
+        return;
+    }
+    killPidTree(pid);
+    try {
+        rmSync(pidFile, { force: true });
+    }
+    catch { /* already gone */ }
+    console.log(`[typecad-hal] debug server stopped (pid ${pid})`);
+}
+// -- serial monitor: post-flash re-enumeration wait --------------------------
+/** How long `--monitor` waits for the port to (re)appear after a flash reset. */
+export const MONITOR_PORT_WAIT_MS = 8000;
+/**
+ * The pyserial port wait run before miniterm (argv built by
+ * serialPortWaitArgs). Polls list_ports — never OPENS the port, because
+ * toggling DTR on an open can itself reset some boards — until the device
+ * name matches case-insensitively or the timeout elapses. Exit codes:
+ * 0 port present, 1 timeout (message printed to stderr), 2 pyserial
+ * unavailable (the caller lets miniterm surface the real error instead of
+ * reporting a bogus timeout).
+ */
+const SERIAL_PORT_WAIT_PY = [
+    'import sys, time',
+    'try:',
+    '    from serial.tools import list_ports',
+    'except Exception:',
+    '    sys.exit(2)',
+    'port, timeout = sys.argv[1], float(sys.argv[2])',
+    'def present():',
+    '    return any(d.device.lower() == port.lower() for d in list_ports.comports())',
+    'if not present():',
+    "    print('waiting for %s to re-enumerate (the board resets after flashing)...' % port, flush=True)",
+    '    end = time.time() + timeout',
+    '    while not present():',
+    '        if time.time() >= end:',
+    "            print('%s did not come back within %ds - some boards re-enumerate under a different port name' % (port, int(timeout)), file=sys.stderr, flush=True)",
+    '            sys.exit(1)',
+    '        time.sleep(0.25)',
+].join('\n');
+/** argv for the pyserial port wait — exported for the toolchain unit tests. */
+export function serialPortWaitArgs(port, timeoutMs) {
+    return ['-c', SERIAL_PORT_WAIT_PY, port, String(timeoutMs / 1000)];
+}
+/**
+ * Wait for `port` to be listed by the venv's pyserial before miniterm opens
+ * it once. True = proceed to miniterm (port present, or the wait itself was
+ * best-effort-skipped — a missing python/pyserial lets miniterm show the
+ * underlying failure); false = the port never came back (message printed).
+ */
+function waitForSerialPort(py, env, cwd, port) {
+    const res = spawnSync(py, serialPortWaitArgs(port, MONITOR_PORT_WAIT_MS), {
+        cwd,
+        env,
+        stdio: 'inherit',
+    });
+    if (res.error || res.status === null || res.status === 2)
+        return true;
+    return res.status === 0;
+}

package/dist/toolchain/runners.d.ts

@@ -0,0 +1,16 @@
+export interface RunnersFacts {
+    /** The board's declared default debug runner (e.g. 'openocd', 'jlink'). */
+    readonly debugRunner?: string;
+    /** Absolute path to the arch gdb binary (config.gdb). */
+    readonly gdb?: string;
+    /** All runners the board configured. */
+    readonly runners: readonly string[];
+}
+/**
+ * Parse the subset of runners.yaml cuttlefish consumes. Exported for tests.
+ * Returns undefined on shapes it does not understand (callers treat as
+ * "no facts" — never crash a build over diagnostics data).
+ */
+export declare function parseRunnersYaml(text: string): RunnersFacts | undefined;
+/** Read the resolved runner facts for a build dir. undefined when absent/unparseable. */
+export declare function readRunnersFacts(buildDir: string): RunnersFacts | undefined;