stikfix 1.5.0 → 1.6.1

package/dist/host/src/native-host.js

@@ -76,25 +76,120 @@ export function handleStartHost(cfg, root, spawnFn = spawn, out) {
         emit({ type: 'ERROR', error: `START_HOST root does not exist: ${resolvedRoot}` });
         return false;
     }
+    const started = spawnDetachedHost(cfg, resolvedRoot, spawnFn);
+    if (!started.ok) {
+        emit({ type: 'ERROR', error: `Failed to start host: ${started.error}` });
+        return false;
+    }
+    emit({ type: 'HOST_STARTING', root: resolvedRoot });
+    return true;
+}
+/**
+ * Spawn the HTTP host as a DETACHED process for `resolvedRoot`, WITHOUT writing
+ * any native-messaging frame — the caller owns the single wire response for this
+ * one-shot process. Returns {ok:true} on a successful spawn, {ok:false,error} on
+ * spawn failure.
+ *
+ * Shared by handleStartHost (which then emits HOST_STARTING) and the GET_TOKEN
+ * auto-start fallback (which then polls for the freshly-written token and emits
+ * TOKEN). Reuses the exact command resolution as before:
+ *   - standalone exe install → `<hostExe> serve --root <root>`
+ *   - npx/node install       → `node <hostEntry> --root <root>`
+ *
+ * CRITICAL (T-09-07): the native host MUST NOT bind/listen itself — it only
+ * spawns a SEPARATE, detached process. NEVER writes to stdout (native-frame
+ * integrity, Pitfall 2). Detached + stdio:'ignore' + unref() so the child
+ * outlives this one-shot native process.
+ */
+function spawnDetachedHost(cfg, resolvedRoot, spawnFn = spawn) {
     const nodePath = typeof cfg.nodePath === 'string' && cfg.nodePath.length > 0 ? cfg.nodePath : process.execPath;
-    const hostEntry = resolveHostEntry(cfg);
-    // CRITICAL (T-09-07): the native host MUST NOT bind/listen itself. It only
-    // spawns a SEPARATE, detached process that is the HTTP host. Detached +
-    // stdio:'ignore' + unref() so the child outlives this one-shot native process.
+    const hostExe = typeof cfg.hostExe === 'string' && cfg.hostExe.length > 0 ? cfg.hostExe : undefined;
+    const spawnCmd = hostExe ?? nodePath;
+    // resolveHostEntry() is only evaluated when actually needed (non-exe/node
+    // install path) — calling it unconditionally in exe-mode would hit the
+    // __dirname fallback for no reason (and __dirname is undefined in the
+    // tsc/ESM test build; production's esbuild CJS bundle is unaffected).
+    const spawnArgs = hostExe
+        ? ['serve', '--root', resolvedRoot]
+        : [resolveHostEntry(cfg), '--root', resolvedRoot];
     try {
-        const child = spawnFn(nodePath, [hostEntry, '--root', resolvedRoot], {
+        const child = spawnFn(spawnCmd, spawnArgs, {
             detached: true,
             stdio: 'ignore',
             windowsHide: true,
         });
         child.unref();
+        return { ok: true };
     }
     catch (err) {
-        emit({ type: 'ERROR', error: `Failed to start host: ${String(err.message)}` });
-        return false;
+        return { ok: false, error: String(err.message) };
     }
-    emit({ type: 'HOST_STARTING', root: resolvedRoot });
-    return true;
+}
+/**
+ * Read the optional `.stikfix-port` for `tokenRoot`, then send the final TOKEN
+ * frame and exit(0). One-shot terminal step for a successful GET_TOKEN — the
+ * only stdout write on this path.
+ */
+function sendTokenFrame(tokenRoot, token, name, notesDir) {
+    // Port is optional — read if present; SW falls back to port scan (A5 fallback).
+    let port;
+    try {
+        const raw = readFileSync(join(tokenRoot, '.stikfix-port'), 'utf8').trim();
+        const parsed = parseInt(raw, 10);
+        if (!isNaN(parsed)) {
+            port = parsed;
+        }
+    }
+    catch {
+        // .stikfix-port absent is OK — SW re-probes (A5)
+    }
+    sendNativeMessage({ type: 'TOKEN', token, port, name, notesDir });
+    process.exit(0);
+}
+/**
+ * GET_TOKEN self-heal: the `.stikfix-token` is missing because the HTTP host has
+ * never started (fresh install) or was stopped. Rather than fail the pairing and
+ * make the user hunt for a "start the host" step, auto-start the host (detached)
+ * and poll briefly for the token file it writes, then return TOKEN. This makes
+ * auto-pair work on the very first popup open with no manual step — the core
+ * reliability promise (a dropped note is a regression).
+ *
+ * NEVER writes to stdout until the single terminal frame (TOKEN or ERROR).
+ */
+function autoStartAndReturnToken(cfg, tokenRoot, name, notesDir) {
+    const tokenPath = join(tokenRoot, '.stikfix-token');
+    const started = spawnDetachedHost(cfg, tokenRoot);
+    if (!started.ok) {
+        sendNativeMessage({
+            type: 'ERROR',
+            error: 'No .stikfix-token in ' + tokenRoot + ' and the host could not be started: ' + started.error,
+        });
+        process.exit(1);
+    }
+    // Poll ~5s (25 × 200ms) for the freshly-started host to bind + write the token.
+    const deadline = Date.now() + 5000;
+    const tick = () => {
+        let tok = '';
+        try {
+            tok = readFileSync(tokenPath, 'utf8').trim();
+        }
+        catch {
+            tok = '';
+        }
+        if (tok.length > 0) {
+            sendTokenFrame(tokenRoot, tok, name, notesDir);
+            return;
+        }
+        if (Date.now() >= deadline) {
+            sendNativeMessage({
+                type: 'ERROR',
+                error: 'Started the Stikfix host but it did not become ready in time (' + tokenRoot + ').',
+            });
+            process.exit(1);
+        }
+        setTimeout(tick, 200);
+    };
+    setTimeout(tick, 200);
 }
 // ---------------------------------------------------------------------------
 // PICK_FOLDER handler — open the OS dialog, validate, respond, exit (Pitfall 8)
@@ -188,38 +283,23 @@ export function main() {
                 notesDir = join(resolvedRoot, 'notes');
             }
             // Token is required ONLY for GET_TOKEN — read it lazily here.
-            let token;
+            let token = '';
             try {
                 token = readFileSync(join(tokenRoot, '.stikfix-token'), 'utf8').trim();
             }
             catch {
-                sendNativeMessage({
-                    type: 'ERROR',
-                    error: 'No .stikfix-token in ' + tokenRoot + '. Start the host first.',
-                });
-                process.exit(1);
-            }
-            // Port is optional — read if present; SW falls back to port scan (A5 fallback)
-            let port;
-            try {
-                const raw = readFileSync(join(tokenRoot, '.stikfix-port'), 'utf8').trim();
-                const parsed = parseInt(raw, 10);
-                if (!isNaN(parsed)) {
-                    port = parsed;
-                }
+                token = '';
             }
-            catch {
-                // .stikfix-port absent is OK — SW re-probes (A5)
+            if (token.length > 0) {
+                // Happy path: host already running, token on disk → send it and exit.
+                sendTokenFrame(tokenRoot, token, name, notesDir);
+                return;
             }
-            // Send token + port (if known) + host identity, then exit (one-shot)
-            sendNativeMessage({
-                type: 'TOKEN',
-                token,
-                port,
-                name,
-                notesDir,
-            });
-            process.exit(0);
+            // Token missing → the host isn't running yet (fresh install / stopped).
+            // Self-heal: start the host and poll for the token, then send TOKEN. This
+            // keeps the terminal-frame contract (one TOKEN or one ERROR) intact.
+            autoStartAndReturnToken(cfg, tokenRoot, name, notesDir);
+            return;
         }
         if (m.type === 'START_HOST') {
             // Spawn a DETACHED HTTP host for the requested root, then exit (one-shot).
@@ -239,12 +319,31 @@ export function main() {
         process.exit(0);
     });
 }
-// Run only when invoked as the entry point (esbuild CJS bundle), never on import.
-// In the esbuild CJS bundle (stikfix-native.cjs), `require`/`module` are CJS
-// scope locals and `require.main === module` is true when run directly. The
-// node:test compile path emits ESM where these are undefined at runtime — the
-// `typeof` guards keep main() from running on import there.
-if (typeof require !== 'undefined' &&
+/**
+ * Async-friendly entry alias for the SEA dispatcher (exe-main.ts). The native
+ * message loop is event-driven, so this resolves immediately after wiring up the
+ * stdin listener; the process stays alive until stdin closes (Chrome closes the
+ * pipe) or a handler calls process.exit. Delegates to main() so the direct
+ * require.main path below is unchanged.
+ */
+export async function runNativeHost() {
+    main();
+}
+function bundledInExe() {
+    try {
+        return typeof __STIKFIX_BUNDLED__ !== 'undefined' && __STIKFIX_BUNDLED__ === true;
+    }
+    catch {
+        return false;
+    }
+}
+// Run only when invoked as the entry point (standalone stikfix-native.cjs),
+// never on import. In that esbuild CJS bundle `require`/`module` are CJS scope
+// locals and `require.main === module` is true when run directly. The node:test
+// compile path emits ESM where these are undefined at runtime — the `typeof`
+// guards keep main() from running on import there.
+if (!bundledInExe() &&
+    typeof require !== 'undefined' &&
     typeof module !== 'undefined' &&
     require.main === module) {
     main();

package/dist/host/stikfix-init.cjs

@@ -30,6 +30,8 @@ var REG_CHROME_KEY = `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${NA
 var REG_EDGE_KEY = `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`;
 var REG_FIREFOX_KEY = `HKCU\\Software\\Mozilla\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`;
 var DEFAULT_GECKO_ID = "stikfix@stikfix.com";
+var CONFIG_DIR = (home) => (0, import_node_path2.join)(home, ".config", "stikfix");
+var CONFIG_PATH = (home) => (0, import_node_path2.join)(CONFIG_DIR(home), "config.json");
 var LAUNCHER_BATCH_FILENAME = "stikfix-host.bat";
 var LAUNCHER_VBS_FILENAME = "stikfix-host.vbs";
 var LAUNCHER_LNK_FILENAME = "Stikfix Host.lnk";
@@ -176,14 +178,17 @@ function createLauncherFiles(opts) {
   const hostEntry = opts.hostEntryPath;
   const rootArg = opts.root;
   const portArg = opts.port !== void 0 ? ` --port ${opts.port}` : "";
+  const useExe = typeof opts.hostExe === "string" && opts.hostExe.length > 0;
+  const hostExe = opts.hostExe ?? "";
   if (plat === "win32") {
+    const batchLaunch = useExe ? `"${hostExe}" serve --root "${rootArg}"${portArg}` : `"${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`;
     const batchContent = [
       "@echo off",
       `rem Stikfix HTTP host launcher \u2014 double-click to start the backend`,
       `rem Generated by: npx stikfix init`,
       `rem Root: ${rootArg}`,
       ``,
-      `"${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`,
+      batchLaunch,
       `if %ERRORLEVEL% NEQ 0 pause`
     ].join("\r\n");
     const batchPath = paths.launcher;
@@ -191,17 +196,20 @@ function createLauncherFiles(opts) {
     written.push(batchPath);
     const vq = (s) => s.replace(/"/g, '""');
     const vbsHostEntry = vq(hostEntry);
+    const vbsHostExe = vq(hostExe);
     const vbsRoot = vq(rootArg);
     const vbsPortArg = opts.port !== void 0 ? ` --port ${opts.port}` : "";
+    const vbsRunLine = useExe ? `sh.Run """" & hostExe & """ serve --root """ & root & """${vbsPortArg}", 0, False` : `sh.Run "cmd /c node """ & hostEntry & """ --root """ & root & """${vbsPortArg}", 0, False`;
     const vbsContent = [
       "Option Explicit",
-      "Dim sh, fso, hostEntry, root, portFile, msg, port, f",
+      "Dim sh, fso, hostEntry, hostExe, root, portFile, msg, port, f",
       'Set sh = CreateObject("WScript.Shell")',
       'Set fso = CreateObject("Scripting.FileSystemObject")',
       `hostEntry = "${vbsHostEntry}"`,
+      `hostExe = "${vbsHostExe}"`,
       `root = "${vbsRoot}"`,
       "' Launch the host hidden (window style 0), do not wait",
-      `sh.Run "cmd /c node """ & hostEntry & """ --root """ & root & """${vbsPortArg}", 0, False`,
+      vbsRunLine,
       "' Give it a moment to bind and write the port file",
       "WScript.Sleep 1800",
       'msg = "Stikfix host is running." & vbCrLf & vbCrLf & "You can start dropping notes."',
@@ -218,21 +226,22 @@ function createLauncherFiles(opts) {
     (0, import_node_fs.writeFileSync)(vbsPath, vbsContent, { encoding: "utf8" });
     written.push(vbsPath);
     if (paths.shortcut) {
-      const lnkPath = paths.shortcut;
+      const guessedLnkPath = paths.shortcut;
       const iconPath = opts.iconPath ?? "";
-      const safeLnkPath = lnkPath.replace(/'/g, "''");
+      const safeLnkFileName = LAUNCHER_LNK_FILENAME.replace(/'/g, "''");
       const safeIconPath = iconPath.replace(/'/g, "''");
       const wscriptPath = (0, import_node_path2.join)(process.env["SystemRoot"] ?? "C:\\Windows", "System32", "wscript.exe");
       const safeWscript = wscriptPath.replace(/'/g, "''");
       const safeVbsPath = vbsPath.replace(/'/g, "''");
-      const psScript = `$ws = New-Object -ComObject WScript.Shell;$s = $ws.CreateShortcut('${safeLnkPath}');$s.TargetPath = '${safeWscript}';$s.Arguments = '"${safeVbsPath}"';$s.Description = 'Start the Stikfix HTTP backend host';` + (safeIconPath ? `$s.IconLocation = '${safeIconPath},0';` : "") + `$s.Save()`;
+      const psScript = `$desktop = [Environment]::GetFolderPath('Desktop');$lnkPath = Join-Path $desktop '${safeLnkFileName}';$ws = New-Object -ComObject WScript.Shell;$s = $ws.CreateShortcut($lnkPath);$s.TargetPath = '${safeWscript}';$s.Arguments = '"${safeVbsPath}"';$s.Description = 'Start the Stikfix HTTP backend host';` + (safeIconPath ? `$s.IconLocation = '${safeIconPath},0';` : "") + `$s.Save();Write-Output $lnkPath`;
       try {
-        (0, import_node_child_process.execFileSync)(
+        const stdout = (0, import_node_child_process.execFileSync)(
           "powershell.exe",
           ["-NoProfile", "-NonInteractive", "-Command", psScript],
-          { timeout: 15e3, stdio: "ignore" }
+          { timeout: 15e3, encoding: "utf8" }
         );
-        written.push(lnkPath);
+        const resolvedLnkPath = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop() ?? guessedLnkPath;
+        written.push(resolvedLnkPath);
       } catch (err) {
         warnings.push(
           `Desktop shortcut creation failed (non-fatal): ${String(err.message)}. The batch file at ${batchPath} can be used directly.`
@@ -245,7 +254,7 @@ function createLauncherFiles(opts) {
       `# Stikfix HTTP host launcher \u2014 double-click in Finder or drag to Dock`,
       `# Generated by: npx stikfix init`,
       ``,
-      `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`
+      useExe ? `exec "${hostExe}" serve --root "${rootArg}"${portArg}` : `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`
     ].join("\n");
     const commandPath = paths.launcher;
     (0, import_node_fs.writeFileSync)(commandPath, commandContent, { encoding: "utf8", mode: 493 });
@@ -256,7 +265,7 @@ function createLauncherFiles(opts) {
       `# Stikfix HTTP host launcher`,
       `# Generated by: npx stikfix init`,
       ``,
-      `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`
+      useExe ? `exec "${hostExe}" serve --root "${rootArg}"${portArg}` : `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`
     ].join("\n");
     const shPath = paths.launcher;
     (0, import_node_fs.writeFileSync)(shPath, shContent, { encoding: "utf8" });
@@ -321,8 +330,8 @@ function registerNativeHost(opts) {
   const home = opts.home ?? (0, import_node_os.homedir)();
   const browser = opts.browser ?? "chrome";
   const manifestPath = nativeManifestPath(plat, home, browser);
-  const wrapperPath = writeNativeWrapper(opts.hostBinPath, plat, home, browser);
-  const manifest = buildManifest(opts.extensionId, wrapperPath, browser);
+  const manifestTarget = opts.directPath ? (0, import_node_path2.resolve)(opts.hostBinPath) : writeNativeWrapper(opts.hostBinPath, plat, home, browser);
+  const manifest = buildManifest(opts.extensionId, manifestTarget, browser);
   writeManifest(manifest, manifestPath);
   if (plat === "win32") {
     const execReg = opts.execReg ?? ((args) => {
@@ -373,6 +382,34 @@ function unregisterNativeHost(opts = {}) {
     }
   }
 }
+function teardownHost(opts = {}) {
+  const plat = opts.plat ?? process.platform;
+  const home = opts.home ?? (0, import_node_os.homedir)();
+  const browser = opts.browser ?? "chrome";
+  const result = {
+    manifestRemoved: true,
+    configPath: CONFIG_PATH(home),
+    configRemoved: false
+  };
+  try {
+    unregisterNativeHost({ plat, home, browser });
+  } catch (err) {
+    result.manifestRemoved = false;
+    result.manifestError = err instanceof Error ? err.message : String(err);
+  }
+  try {
+    unregisterStartup({ plat, home });
+  } catch (err) {
+    result.startupError = err instanceof Error ? err.message : String(err);
+  }
+  try {
+    (0, import_node_fs.rmSync)(result.configPath, { force: true });
+    result.configRemoved = true;
+  } catch {
+    result.configRemoved = false;
+  }
+  return result;
+}
 
 // host/src/extension-id.ts
 var import_node_crypto2 = require("node:crypto");
@@ -430,8 +467,8 @@ function resolveStartupChoice(forceOn, forceOff, isTTY) {
   }
   return false;
 }
-var CONFIG_DIR = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".config", "stikfix");
-var CONFIG_PATH = (0, import_node_path3.join)(CONFIG_DIR, "config.json");
+var CONFIG_DIR2 = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".config", "stikfix");
+var CONFIG_PATH2 = (0, import_node_path3.join)(CONFIG_DIR2, "config.json");
 if (subcommand === "init") {
   const rawRoot = values["root"];
   const rawExtId = values["extension-id"];
@@ -449,9 +486,9 @@ if (subcommand === "init") {
   const name = (0, import_node_path3.basename)(root);
   const notesDir = (0, import_node_path3.join)(root, "notes");
   const hostEntryPath = (0, import_node_path3.resolve)((0, import_node_path3.join)(__dirname, "src", "index.js"));
-  (0, import_node_fs2.mkdirSync)(CONFIG_DIR, { recursive: true });
+  (0, import_node_fs2.mkdirSync)(CONFIG_DIR2, { recursive: true });
   const config = { root, name, notesDir, hostEntry: hostEntryPath, nodePath: process.execPath };
-  (0, import_node_fs2.writeFileSync)(CONFIG_PATH, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 384 });
+  (0, import_node_fs2.writeFileSync)(CONFIG_PATH2, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 384 });
   const hostBinPath = (0, import_node_path3.resolve)((0, import_node_path3.join)(__dirname, "stikfix-native.cjs"));
   try {
     registerNativeHost({ extensionId, hostBinPath, browser });
@@ -540,9 +577,9 @@ if (subcommand === "init") {
   console.log("");
   console.log("  2. Start the backend \u2014 double-click the desktop launcher:");
   if (process.platform === "win32") {
-    const lnkPath = (0, import_node_path3.join)((0, import_node_os2.homedir)(), "Desktop", "Stikfix Host.lnk");
+    const lnkPath = launcherResult.written.find((p) => p.endsWith(".lnk")) ?? "";
     const batchPath = launcherResult.written.find((p) => p.endsWith(".bat")) ?? "";
-    if ((0, import_node_fs2.existsSync)(lnkPath)) {
+    if (lnkPath && (0, import_node_fs2.existsSync)(lnkPath)) {
       console.log('       Desktop shortcut: "Stikfix Host" (icon on your Desktop)');
     } else if (batchPath) {
       console.log("       Batch file: " + batchPath);
@@ -567,17 +604,13 @@ if (subcommand === "init") {
   console.log("  npx --yes stikfix@latest init --root " + root);
 } else if (subcommand === "uninstall") {
   const browser = resolveBrowser(values["browser"]);
-  try {
-    unregisterNativeHost({ browser });
-  } catch (err) {
-    console.error("stikfix uninstall: error removing native-host manifest:", String(err));
+  const teardown = teardownHost({ browser });
+  if (teardown.manifestError) {
+    console.error("stikfix uninstall: error removing native-host manifest:", teardown.manifestError);
   }
-  try {
-    unregisterStartup();
-  } catch (err) {
-    console.error("stikfix uninstall: error removing startup entry:", String(err));
+  if (teardown.startupError) {
+    console.error("stikfix uninstall: error removing startup entry:", teardown.startupError);
   }
-  (0, import_node_fs2.rmSync)(CONFIG_PATH, { force: true });
   console.log("stikfix: native host unregistered.");
   console.log("  manifest removed");
   console.log("  launcher files removed");

package/dist/host/stikfix-native.cjs

@@ -23,6 +23,7 @@ __export(native_host_exports, {
   handlePickFolder: () => handlePickFolder,
   handleStartHost: () => handleStartHost,
   main: () => main,
+  runNativeHost: () => runNativeHost,
   validateChosenFolder: () => validateChosenFolder
 });
 module.exports = __toCommonJS(native_host_exports);
@@ -210,21 +211,76 @@ function handleStartHost(cfg, root, spawnFn = import_node_child_process2.spawn,
     emit({ type: "ERROR", error: `START_HOST root does not exist: ${resolvedRoot}` });
     return false;
   }
+  const started = spawnDetachedHost(cfg, resolvedRoot, spawnFn);
+  if (!started.ok) {
+    emit({ type: "ERROR", error: `Failed to start host: ${started.error}` });
+    return false;
+  }
+  emit({ type: "HOST_STARTING", root: resolvedRoot });
+  return true;
+}
+function spawnDetachedHost(cfg, resolvedRoot, spawnFn = import_node_child_process2.spawn) {
   const nodePath = typeof cfg.nodePath === "string" && cfg.nodePath.length > 0 ? cfg.nodePath : process.execPath;
-  const hostEntry = resolveHostEntry(cfg);
+  const hostExe = typeof cfg.hostExe === "string" && cfg.hostExe.length > 0 ? cfg.hostExe : void 0;
+  const spawnCmd = hostExe ?? nodePath;
+  const spawnArgs = hostExe ? ["serve", "--root", resolvedRoot] : [resolveHostEntry(cfg), "--root", resolvedRoot];
   try {
-    const child = spawnFn(nodePath, [hostEntry, "--root", resolvedRoot], {
+    const child = spawnFn(spawnCmd, spawnArgs, {
       detached: true,
       stdio: "ignore",
       windowsHide: true
     });
     child.unref();
+    return { ok: true };
   } catch (err) {
-    emit({ type: "ERROR", error: `Failed to start host: ${String(err.message)}` });
-    return false;
+    return { ok: false, error: String(err.message) };
   }
-  emit({ type: "HOST_STARTING", root: resolvedRoot });
-  return true;
+}
+function sendTokenFrame(tokenRoot, token, name, notesDir) {
+  let port;
+  try {
+    const raw = (0, import_node_fs2.readFileSync)((0, import_node_path2.join)(tokenRoot, ".stikfix-port"), "utf8").trim();
+    const parsed = parseInt(raw, 10);
+    if (!isNaN(parsed)) {
+      port = parsed;
+    }
+  } catch {
+  }
+  sendNativeMessage({ type: "TOKEN", token, port, name, notesDir });
+  process.exit(0);
+}
+function autoStartAndReturnToken(cfg, tokenRoot, name, notesDir) {
+  const tokenPath = (0, import_node_path2.join)(tokenRoot, ".stikfix-token");
+  const started = spawnDetachedHost(cfg, tokenRoot);
+  if (!started.ok) {
+    sendNativeMessage({
+      type: "ERROR",
+      error: "No .stikfix-token in " + tokenRoot + " and the host could not be started: " + started.error
+    });
+    process.exit(1);
+  }
+  const deadline = Date.now() + 5e3;
+  const tick = () => {
+    let tok = "";
+    try {
+      tok = (0, import_node_fs2.readFileSync)(tokenPath, "utf8").trim();
+    } catch {
+      tok = "";
+    }
+    if (tok.length > 0) {
+      sendTokenFrame(tokenRoot, tok, name, notesDir);
+      return;
+    }
+    if (Date.now() >= deadline) {
+      sendNativeMessage({
+        type: "ERROR",
+        error: "Started the Stikfix host but it did not become ready in time (" + tokenRoot + ")."
+      });
+      process.exit(1);
+    }
+    setTimeout(tick, 200);
+  };
+  setTimeout(tick, 200);
 }
 async function handlePickFolder(origin, pickFn = pickFolder, plat = process.platform, out) {
   let chosen;
@@ -273,33 +329,18 @@ function main() {
         name = (0, import_node_path2.basename)(resolvedRoot);
         notesDir = (0, import_node_path2.join)(resolvedRoot, "notes");
       }
-      let token;
+      let token = "";
       try {
         token = (0, import_node_fs2.readFileSync)((0, import_node_path2.join)(tokenRoot, ".stikfix-token"), "utf8").trim();
       } catch {
-        sendNativeMessage({
-          type: "ERROR",
-          error: "No .stikfix-token in " + tokenRoot + ". Start the host first."
-        });
-        process.exit(1);
+        token = "";
       }
-      let port;
-      try {
-        const raw = (0, import_node_fs2.readFileSync)((0, import_node_path2.join)(tokenRoot, ".stikfix-port"), "utf8").trim();
-        const parsed = parseInt(raw, 10);
-        if (!isNaN(parsed)) {
-          port = parsed;
-        }
-      } catch {
+      if (token.length > 0) {
+        sendTokenFrame(tokenRoot, token, name, notesDir);
+        return;
       }
-      sendNativeMessage({
-        type: "TOKEN",
-        token,
-        port,
-        name,
-        notesDir
-      });
-      process.exit(0);
+      autoStartAndReturnToken(cfg, tokenRoot, name, notesDir);
+      return;
     }
     if (m.type === "START_HOST") {
       const ok = handleStartHost(cfg, m.root);
@@ -315,7 +356,17 @@ function main() {
     process.exit(0);
   });
 }
-if (typeof require !== "undefined" && typeof module !== "undefined" && require.main === module) {
+async function runNativeHost() {
+  main();
+}
+function bundledInExe() {
+  try {
+    return typeof __STIKFIX_BUNDLED__ !== "undefined" && __STIKFIX_BUNDLED__ === true;
+  } catch {
+    return false;
+  }
+}
+if (!bundledInExe() && typeof require !== "undefined" && typeof module !== "undefined" && require.main === module) {
   main();
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -323,5 +374,6 @@ if (typeof require !== "undefined" && typeof module !== "undefined" && require.m
   handlePickFolder,
   handleStartHost,
   main,
+  runNativeHost,
   validateChosenFolder
 });

package/dist/lib/pin-position.js

@@ -0,0 +1,69 @@
+/**
+ * URL-path matching and pin position computation for stikfix persistent pins.
+ *
+ * matchesUrlPath + computePinPosition — pure, node:test-safe (no DOM/chrome at module level).
+ * Scroll offsets and anchor rects are PASSED AS PARAMETERS by the caller (pin.ts in Plan 04),
+ * which supplies window.scrollX/scrollY and el.getBoundingClientRect() at render time.
+ *
+ * INVARIANT: No top-level browser API access — no window/document/chrome references.
+ * This module imports cleanly under node:test.
+ */
+/**
+ * Compare two URLs by pathname only, ignoring query string and fragment (D-02).
+ * Returns false (not throws) on any malformed URL input.
+ *
+ * @param noteUrl  The URL stored in the note's YAML frontmatter
+ * @param pageUrl  The current page URL from chrome.tabs.get
+ */
+export function matchesUrlPath(noteUrl, pageUrl) {
+    try {
+        const notePath = new URL(noteUrl).pathname;
+        const pagePath = new URL(pageUrl).pathname;
+        return notePath === pagePath;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compute the CSS viewport position for an on-page pin — pure, DOM-free.
+ *
+ * Branch logic:
+ *   - orphaned || anchorRect === null: orphaned-fallback at last-known page-absolute
+ *     rect minus scroll offsets → { left: storedRect.x - scrollX, top: storedRect.y - scrollY, orphaned: true }
+ *   - !orphaned && anchorRect !== null: use anchorRect x/y directly (already in
+ *     fixed/viewport coords from getBoundingClientRect or stored viewport coords
+ *     for free notes) → { left: anchorRect.x, top: anchorRect.y, orphaned: false }
+ *
+ * The caller (pin.ts) passes:
+ *   - anchorRect: el.getBoundingClientRect() for element pins, stored viewport
+ *     coords {x,y,width:0,height:0} for free pins, or null when selector misses.
+ *   - storedRect: page-absolute rect from frontmatter (for orphaned-fallback).
+ *   - scrollX/scrollY: window.scrollX / window.scrollY at call time.
+ *   - orphaned: true when the selector re-query returned null.
+ *
+ * NEVER reads window.scrollX or window.scrollY internally — caller supplies them.
+ *
+ * @param anchorRect  Live fixed-coord rect from getBoundingClientRect, or null
+ * @param storedRect  Page-absolute rect from frontmatter (orphaned fallback), or null
+ * @param scrollX     window.scrollX at call time (passed by caller)
+ * @param scrollY     window.scrollY at call time (passed by caller)
+ * @param orphaned    true when selector matched nothing on the current page
+ */
+export function computePinPosition(anchorRect, storedRect, scrollX, scrollY, orphaned) {
+    if (orphaned || anchorRect === null) {
+        // Orphaned fallback: last-known page-absolute rect → convert to viewport via scroll
+        return {
+            left: (storedRect?.x ?? 0) - scrollX,
+            top: (storedRect?.y ?? 0) - scrollY,
+            orphaned: true,
+        };
+    }
+    // Element-anchored (live getBoundingClientRect in fixed/viewport coords)
+    // OR free-floating (stored viewport coords already in anchorRect x/y)
+    return {
+        left: anchorRect.x,
+        top: anchorRect.y,
+        orphaned: false,
+    };
+}