@dumbmice/pi-mailbridge 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.1.2 — 2026-11-13
+
+The release that fixes the ways this package could quietly do the wrong thing.
+
+- **A renamed file could be mailed as an image.** `![shot](./x.png)` checked magic bytes;
+  `[notes](./x.png)` checked only the extension, so any file called `.png` went out labelled
+  `image/png` - a config, a key. The link path now sniffs too, refuses a mismatch, and labels the
+  part with the type the bytes actually are.
+- **A checkout ran the previous build.** Both the daemon a session spawns and the `pi-mailbridge`
+  CLI preferred `dist/` whenever it existed, and `dist/` is only rebuilt by `pretest`
+  /`prepublishOnly` - so an edit to `src/daemon/*` ran old code with an unchanged `API_VERSION`
+  and no warning. A checkout now runs its sources; an installed package still runs the build.
+- **An incomplete install said the wrong thing.** With no `dist/`, the CLI spawned the TypeScript
+  entry from inside `node_modules` and died on Node's `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`
+  instead of saying "reinstall the package".
+- **`main` named a file plain Node cannot import.** It points at `dist/extension.js` now; pi never
+  read `main` (it uses `pi.extensions`), so the field only misled other tools.
+- **`daemon.host` was never validated** - the one setting that removes the loopback assumption.
+  A non-loopback host is now reported by `/mailbridge check` and fails `pi-mailbridge --check`,
+  the same way an `allowSelfReplies` + DMARC combination already does.
+- **The package page showed alt text instead of the diagram.** npm renders the README out of the
+  tarball, where a relative `src` has no base; the images and the ten doc links are absolute now,
+  and a test keeps them that way.
+- SECURITY.md §2.1 states the assumption the DMARC check rests on (the topmost
+  `Authentication-Results` is your provider's only if your provider writes one), with the measured
+  both-directions failure and the two responses that work.
+
 ## 0.1.1 — 2026-11-13
 
 No behaviour change. This is the release that proves the pipeline: publishing now happens in CI

package/README.md

@@ -8,7 +8,7 @@ continues**, with your answer as the next message. Notifications also carry rend
 images embedded in the body where the agent put them, and any local file it linked attached with
 its real name.
 
-![A pi-mailbridge notification in a mail client: a decision request with rendered Markdown, a recommendation, and a build log attached](./docs/images/notification.png)
+![A pi-mailbridge notification in a mail client: a decision request with rendered Markdown, a recommendation, and a build log attached](https://raw.githubusercontent.com/DumbMice/pi-mailbridge/main/docs/images/notification.png)
 
 - **Your inbox is the client.** No app, no account, no relay, no push service. Any device with
   email works: a phone, a tablet, another PC, a webmail tab.
@@ -22,7 +22,7 @@ its real name.
   leaves it unread, so nothing is lost.
 
 > **This turns your inbox into a control channel for an agent that can run shell commands.**
-> Read [docs/SECURITY.md](./docs/SECURITY.md) before installing, and point it at a mailbox you
+> Read [docs/SECURITY.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/SECURITY.md) before installing, and point it at a mailbox you
 > would not mind an agent reading.
 
 ## Install
@@ -56,9 +56,10 @@ protocol is left alone. Without that, a new extension
 would mint routing ids an old daemon cannot resolve, and replies would be rejected with the
 cursor already past them.
 
-The replacement is: shut the old daemon down (`POST /shutdown`), spawn the compiled daemon that is
-already on disk (`dist/daemon/main.js` — no build runs at runtime; the package is built once, at
-publish time, and `pi install` receives the build), and have this session re-create its client. Queued
+The replacement is: shut the old daemon down (`POST /shutdown`), spawn the daemon entry this copy of
+the package carries — the compiled `dist/daemon/main.js` for an installed package (no build runs at
+runtime: it is built once, at publish time), or `src/daemon/main.ts` when you run from a checkout —
+and have this session re-create its client. Queued
 replies, the cursor and the journal are on disk and untouched, so the gap costs nothing but the
 seconds the old daemon spent not watching IMAP; the mode survives because it is a file. If the respawn fails, the session warns and keeps polling, retrying within a minute;
 `/mailbridge restart` forces it.
@@ -102,7 +103,7 @@ both are quiet:
 
 Let a turn settle and the first notification arrives. Reply to it from anywhere.
 
-Prefer to write the config yourself? Copy [`config.example.json`](./config.example.json).
+Prefer to write the config yourself? Copy [`config.example.json`](https://github.com/DumbMice/pi-mailbridge/blob/main/config.example.json).
 
 ### Start watching from now
 
@@ -289,7 +290,7 @@ Attachments come only from **the agent's project directory**, and only for allow
 keeps the obvious key *filenames* out of an accidental attach; it is not a content filter — an
 agent told to `cp ~/.ssh/id_rsa notes.txt` or `tar` a directory can still mail the result. Start
 pi in a project rather than in `$HOME`, and see
-[docs/SECURITY.md](./docs/SECURITY.md) §6b for the full boundary.
+[docs/SECURITY.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/SECURITY.md) §6b for the full boundary.
 
 ## When it helps
 
@@ -341,7 +342,7 @@ Every scan records why each message was refused, so this is answerable:
 ```
 
 ```
-daemon: healthy (http://127.0.0.1:4177) — daemon version 0.1.1
+daemon: healthy (http://127.0.0.1:4177) — daemon version 0.1.2
 device: dev-box-7
 mode: on
 imap: connected
@@ -416,12 +417,12 @@ loop guard → auto-generated/bounce → sender allowlist → DMARC → our own
 durable ack. Routing identifiers never authorize anything: authorization is the allowlist and
 DMARC alone (DMARC is off in single-mailbox mode). Prefer a dedicated account or a filtered
 folder. What is stored, what a leaked token means, and the threat model in full:
-[docs/SECURITY.md](./docs/SECURITY.md).
+[docs/SECURITY.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/SECURITY.md).
 
 ## Configuration
 
 `~/.config/pi-mailbridge/config.json`, merged over built-in defaults, then `PI_MAILBRIDGE_*`
-environment variables. A working example: [`config.example.json`](./config.example.json).
+environment variables. A working example: [`config.example.json`](https://github.com/DumbMice/pi-mailbridge/blob/main/config.example.json).
 
 | Key | Default | Meaning |
 | --- | --- | --- |
@@ -487,7 +488,7 @@ pi-mailbridge --auth      # prints a URL + code, waits for approval
 ```
 
 Registering the app is free and takes about two minutes (Entra → *Allow public client flows*).
-Walkthrough, scope tables and the Gmail equivalent: [docs/OAUTH.md](./docs/OAUTH.md).
+Walkthrough, scope tables and the Gmail equivalent: [docs/OAUTH.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/OAUTH.md).
 
 **In mainland China, use QQ or 163** — 授权码 works exactly like an app password:
 
@@ -506,7 +507,7 @@ tenant, no refresh token that dies weekly. Gmail *OAuth* is the harder route —
 **Personal Outlook has a real caveat:** Microsoft sometimes rejects IMAP/SMTP OAuth2 even with a
 valid token (`User is authenticated but not connected`, `SmtpClientAuthentication is disabled`).
 That is their side. The reliable answer is Microsoft Graph, which is not implemented here yet;
-[docs/OAUTH.md](./docs/OAUTH.md) explains the options, including turnkey services.
+[docs/OAUTH.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/OAUTH.md) explains the options, including turnkey services.
 
 ### A token command instead
 
@@ -539,7 +540,7 @@ the daemon without editing your config file:
 
 | Tool | Behaviour |
 | --- | --- |
-| `request_decision` | Emails a question with optional options and a recommendation, then ends the turn. One outstanding decision per session. Ending the turn is a convention, not an enforced gate — see [docs/SECURITY.md](./docs/SECURITY.md) §3. |
+| `request_decision` | Emails a question with optional options and a recommendation, then ends the turn. One outstanding decision per session. Ending the turn is a convention, not an enforced gate — see [docs/SECURITY.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/SECURITY.md) §3. |
 | `notify_user` | One-way update. Does not reserve a slot and does not wait. |
 
 Both refuse cleanly when email mode is off or the daemon is unreachable.
@@ -565,7 +566,7 @@ that is the credential that actually reaches your mailbox.
 
 ## How it works
 
-![Diagram: the pi session sends through the local daemon over SMTP to your mailbox; you reply from any device; the daemon reads it over IMAP, authorizes, routes and persists it; the session claims it, injects it, and acknowledges, which marks the mail seen](./docs/images/flow.svg)
+![Diagram: the pi session sends through the local daemon over SMTP to your mailbox; you reply from any device; the daemon reads it over IMAP, authorizes, routes and persists it; the session claims it, injects it, and acknowledges, which marks the mail seen](https://raw.githubusercontent.com/DumbMice/pi-mailbridge/main/docs/images/flow.svg)
 
 The numbered path is the whole product. **1** The agent finishes its turn and goes idle — that is
 the normal case, one mail per finished turn — or it stops to ask you a question; either way the
@@ -577,12 +578,12 @@ journalled.
 
 One daemon per machine owns the mailbox; sessions never touch IMAP. `smoke` and `prime` are the
 deliberate exceptions — each opens one short-lived connection. Design notes, the failure-mode
-table and the module map: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and
-[docs/MAPPING.md](./docs/MAPPING.md).
+table and the module map: [docs/ARCHITECTURE.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/ARCHITECTURE.md) and
+[docs/MAPPING.md](https://github.com/DumbMice/pi-mailbridge/blob/main/docs/MAPPING.md).
 
 ## Status
 
-`0.1.1` — feature-complete for the single-user, one-mailbox case, and exercised end to end
+`0.1.2` — feature-complete for the single-user, one-mailbox case, and exercised end to end
 against a live QQ mailbox in both layouts: two addresses (DMARC verified on the reply) and one
 address for both roles (self-delivery, the self-echo guard, and a reply routed by the chain).
 

package/bin/pi-mailbridge.mjs

@@ -3,21 +3,30 @@
 //
 // From an installed package this loads the compiled `dist/` build: Node refuses to strip
 // TypeScript inside `node_modules` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), which is why
-// the daemon is built rather than shipped as `.ts`. A checkout without a build falls back to
-// running the sources with the flag, which is how development and the tests use it.
+// the daemon is built rather than shipped as `.ts`.
+//
+// A checkout is the mirror image: it must run its SOURCES even when a build is sitting there.
+// `dist/` is gitignored and rebuilt only by `pretest`/`prepublishOnly`, so preferring it would
+// silently run the previous build — with an unchanged `API_VERSION`, nothing would notice. The
+// `node_modules` path segment is the discriminator because it is the actual constraint, and it is
+// the same rule src/daemon/script.ts applies to the daemon a session spawns.
 import { existsSync } from "node:fs"
 import { fileURLToPath } from "node:url"
+import { sep } from "node:path"
 
+const here = fileURLToPath(import.meta.url)
+const installed = here.split(sep).includes("node_modules")
 const compiled = new URL("../dist/daemon/main.js", import.meta.url)
 const source = new URL("../src/daemon/main.ts", import.meta.url)
+const runCompiled = existsSync(fileURLToPath(compiled)) && (installed || !existsSync(fileURLToPath(source)))
 
-if (existsSync(fileURLToPath(compiled))) {
+if (runCompiled) {
 	const { main } = await import(compiled.href)
 	main().catch((error) => {
 		console.error(`pi-mailbridge: fatal: ${error instanceof Error ? error.message : String(error)}`)
 		process.exit(1)
 	})
-} else if (existsSync(fileURLToPath(source))) {
+} else if (!installed && existsSync(fileURLToPath(source))) {
 	const { spawn } = await import("node:child_process")
 	const child = spawn(
 		process.execPath,
@@ -25,6 +34,11 @@ if (existsSync(fileURLToPath(compiled))) {
 		{ stdio: "inherit" },
 	)
 	child.on("exit", (code) => process.exit(code ?? 1))
+} else if (installed) {
+	// Spawning the .ts from here would fail with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING,
+	// which tells a user nothing about the real problem: the install is incomplete.
+	console.error("pi-mailbridge: this install has no compiled build (dist/); reinstall the package")
+	process.exit(1)
 } else {
 	console.error("pi-mailbridge: no dist/ or src/ found beside this bin; reinstall the package")
 	process.exit(1)

package/dist/core/config.js

@@ -235,6 +235,12 @@ export function loadConfig(env = process.env) {
             resolved.daemon = { ...resolved.daemon, scanIntervalSecs: n };
         }
     }
+    // The one setting that removes the loopback assumption. SECURITY.md says "do not"; saying it
+    // only in the docs means a hand-edited config gets no feedback at all.
+    const host = String(resolved.daemon.host ?? "").trim().toLowerCase();
+    if (host && !(host === "localhost" || host === "::1" || host === "[::1]" || host === "127.0.0.1" || host.startsWith("127."))) {
+        warnings.push(`daemon.host is "${resolved.daemon.host}", not loopback — there is no TLS and the bearer token is the only guard; leave it at 127.0.0.1 unless you know why`);
+    }
     const imap = resolved.mail.imap;
     if (!imap.host || !imap.user)
         warnings.push("mail.imap.host and mail.imap.user are required");

package/dist/core/inline-images.js

@@ -8,7 +8,8 @@
 //                                      relative path and a cid: anchor is unreliable
 //
 // The result is mailed, so the safety rules are the point: an image must sniff as an image
-// (magic bytes, not an extension), a non-image must have an allowlisted extension, every
+// (magic bytes, not an extension) whether it was written as an image or as a link, a non-image
+// must have an allowlisted extension, every
 // file is size- and count-capped, and anything unreadable degrades to a sentence instead of
 // a broken link. Content is hashed, so one file referenced twice rides once.
 //
@@ -331,6 +332,18 @@ export function inlineLocalImages(html, options = {}) {
             skipped.push({ src: href, reason: "not-found" });
             return `${inner} ${note("not attached", "file not found")}`;
         }
+        // An extension is a claim, not a fact. The image rules above sniff; without this the link
+        // path did not, so `[notes](./notes.png)` mailed any bytes at all labelled image/png -
+        // the one thing the allowlist exists to prevent. Raster types are checkable; SVG is XML,
+        // has no signature to check, and is attached as a file rather than inlined.
+        let attachmentType = contentType;
+        if (contentType.startsWith("image/") && contentType !== "image/svg+xml") {
+            const kind = sniffImage(bytes);
+            if (!kind)
+                return refuse("not-an-image", "not an image");
+            // Name it for what it is: a real PNG called report.jpg should arrive as image/png.
+            attachmentType = kind.contentType;
+        }
         // Same content, same part: a report linked from two places is attached once.
         const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
         const existing = byCid.get(`file-${digest}`);
@@ -342,7 +355,7 @@ export function inlineLocalImages(html, options = {}) {
             const attachment = {
                 filename,
                 content: bytes,
-                contentType,
+                contentType: attachmentType,
                 contentDisposition: "attachment",
             };
             byCid.set(`file-${digest}`, attachment);

package/dist/daemon/script.js

@@ -7,7 +7,7 @@
 //
 // Pure and exported so both layouts can be tested without installing a package.
 import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 /**
  * Resolve the daemon script for the module at `moduleUrl`.
@@ -15,26 +15,42 @@ import { fileURLToPath } from "node:url";
  * - `dist/extension.js`     -> `dist/daemon/main.js`
  * - `src/extension.ts`      -> `dist/daemon/main.js` when built (a published install)
  * - `src/extension.ts` only -> `src/daemon/main.ts` (a checkout, run with the flag)
+ *
+ * In a checkout the SOURCE wins even when `dist/` exists. `dist/` is gitignored and rebuilt only
+ * by `pretest`/`prepublishOnly`, so editing `src/daemon/*` without rebuilding would otherwise run
+ * the previous build - with an unchanged `API_VERSION`, so nothing detects the mismatch and the
+ * only symptom is a fix that appears not to work. A published install has no source to prefer.
  */
 export function resolveDaemonScript(moduleUrl, exists = existsSync) {
     const here = fileURLToPath(moduleUrl);
     const dir = dirname(here);
     const root = dirname(dir);
     const compiled = here.endsWith(".js");
+    // A dependency install is the only place `dist/` is the authority; everything else is a
+    // checkout someone is editing.
+    const installed = here.split(sep).includes("node_modules");
+    const built = join(root, "dist", "daemon", "main.js");
+    const source = join(dir, "daemon", "main.ts");
     const candidates = compiled
         ? [
             // dist/extension.js -> dist/daemon/main.js
             join(dir, "daemon", "main.js"),
-            join(root, "dist", "daemon", "main.js"),
-            join(dir, "daemon", "main.ts"),
+            built,
+            source,
         ]
-        : [
-            // src/extension.ts -> the build, when the package was published
-            join(root, "dist", "daemon", "main.js"),
-            join(dir, "daemon", "main.js"),
-            // a checkout without a build
-            join(dir, "daemon", "main.ts"),
-        ];
+        : installed
+            ? [
+                // src/extension.ts inside node_modules: the compiled daemon, or nothing
+                built,
+                join(dir, "daemon", "main.js"),
+                source,
+            ]
+            : [
+                // a checkout: what the editor has, not what the last build left behind
+                source,
+                built,
+                join(dir, "daemon", "main.js"),
+            ];
     for (const candidate of candidates) {
         if (exists(candidate))
             return candidate;

package/docs/SECURITY.md

@@ -40,6 +40,28 @@ traverses relays, so the **topmost** `Authentication-Results` is the one the fin
 hop — your provider — wrote on delivery. A sender's forged header necessarily ends
 up *below* it.
 
+**That argument rests on one assumption: your provider adds a header at all.** If the delivering
+relay stamps no `Authentication-Results`, the topmost one is whatever the sender wrote — so a
+forged `dmarc=pass` is accepted, while your own genuine replies fail `dmarc-missing`. Measured
+here, not theorised:
+
+```
+From: <an allowlisted address>, only one Authentication-Results, forged by the sender  -> accepted
+From: <the same address>, genuinely sent through a relay that stamps nothing           -> rejected (dmarc-missing)
+```
+
+It is a quiet failure in both directions at once: a spoofed message gets in *and* real mail appears
+broken, which invites turning `requireDmarcPass` off entirely — the worst response. Two defences:
+
+1. **Pin it.** Set `security.trustedAuthservId` to your provider's authserv-id (the token before
+   the first `;` in its header). A message without that header then fails closed instead of
+   trusting whatever is topmost. Do not pin Microsoft consumer accounts — outlook.com emits bare
+   headers with no authserv-id (rule 3 below).
+2. **Measure it.** `pi-mailbridge --smoke` sends one real mail and re-opens the folder; read the
+   delivered copy's headers. If it has no `Authentication-Results`, DMARC cannot help on that
+   provider and `requireDmarcPass: true` is a coin flip. This is not automated yet — it is the
+   reason `--check` prints a note when `trustedAuthservId` is unset.
+
 Rules:
 
 1. Read the **topmost** `Authentication-Results` header and require `dmarc=pass`
@@ -243,7 +265,10 @@ model output. The controls, all fail-closed:
 - **The daemon's own config and state directories are never attached**, whatever the `cwd`.
 - **An extension allowlist** (`pdf txt log md csv tsv json yml yaml xml html zip gz tar docx xlsx
   pptx`, plus `png jpg jpeg gif webp svg` for links and the sniffed image types inline)
-  keeps the obvious key filenames out of an accidental attach. It is not a content filter:
+  keeps the obvious key filenames out of an accidental attach. A linked file whose extension
+  claims a raster image must also **sniff** as one (a `.png` full of text is refused, and a real
+  PNG misnamed `.jpg` is attached as `image/png`); SVG is the exception, since XML has no
+  signature — it is an attachment, never inlined. It is not a content filter:
   `cp ~/.ssh/id_rsa notes.txt` or `tar czf k.tar ~/.ssh` defeats it, and `realpath` cannot see a
   hardlink. Treat it as a guard rail against a naive single-shot injection, not a sandbox.
 - **Size caps**: 5 MB per inline image and 15 MB per linked file (fixed), and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dumbmice/pi-mailbridge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drive Pi coding-agent sessions from your mailbox: get an email when an agent settles, reply to resume that exact session.",
   "keywords": [
     "pi",
@@ -48,7 +48,7 @@
       "./src/extension.ts"
     ]
   },
-  "main": "./src/extension.ts",
+  "main": "./dist/extension.js",
   "scripts": {
     "daemon": "node --experimental-strip-types src/daemon/main.ts",
     "typecheck": "tsc --noEmit",

package/src/core/config.ts

@@ -317,6 +317,15 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ResolvedConfig
 		}
 	}
 
+	// The one setting that removes the loopback assumption. SECURITY.md says "do not"; saying it
+	// only in the docs means a hand-edited config gets no feedback at all.
+	const host = String(resolved.daemon.host ?? "").trim().toLowerCase()
+	if (host && !(host === "localhost" || host === "::1" || host === "[::1]" || host === "127.0.0.1" || host.startsWith("127."))) {
+		warnings.push(
+			`daemon.host is "${resolved.daemon.host}", not loopback — there is no TLS and the bearer token is the only guard; leave it at 127.0.0.1 unless you know why`,
+		)
+	}
+
 	const imap = resolved.mail.imap
 	if (!imap.host || !imap.user) warnings.push("mail.imap.host and mail.imap.user are required")
 	if (!resolved.mail.to) warnings.push("mail.to is required")

package/src/core/inline-images.ts

@@ -8,7 +8,8 @@
 //                                      relative path and a cid: anchor is unreliable
 //
 // The result is mailed, so the safety rules are the point: an image must sniff as an image
-// (magic bytes, not an extension), a non-image must have an allowlisted extension, every
+// (magic bytes, not an extension) whether it was written as an image or as a link, a non-image
+// must have an allowlisted extension, every
 // file is size- and count-capped, and anything unreadable degrades to a sentence instead of
 // a broken link. Content is hashed, so one file referenced twice rides once.
 //
@@ -396,6 +397,18 @@ export function inlineLocalImages(html: string, options: InlineOptions = {}): In
 			return `${inner} ${note("not attached", "file not found")}`
 		}
 
+		// An extension is a claim, not a fact. The image rules above sniff; without this the link
+		// path did not, so `[notes](./notes.png)` mailed any bytes at all labelled image/png -
+		// the one thing the allowlist exists to prevent. Raster types are checkable; SVG is XML,
+		// has no signature to check, and is attached as a file rather than inlined.
+		let attachmentType = contentType
+		if (contentType.startsWith("image/") && contentType !== "image/svg+xml") {
+			const kind = sniffImage(bytes)
+			if (!kind) return refuse("not-an-image", "not an image")
+			// Name it for what it is: a real PNG called report.jpg should arrive as image/png.
+			attachmentType = kind.contentType
+		}
+
 		// Same content, same part: a report linked from two places is attached once.
 		const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 16)
 		const existing = byCid.get(`file-${digest}`)
@@ -407,7 +420,7 @@ export function inlineLocalImages(html: string, options: InlineOptions = {}): In
 			const attachment: InlineAttachment = {
 				filename,
 				content: bytes,
-				contentType,
+				contentType: attachmentType,
 				contentDisposition: "attachment",
 			}
 			byCid.set(`file-${digest}`, attachment)

package/src/daemon/script.ts

@@ -8,7 +8,7 @@
 // Pure and exported so both layouts can be tested without installing a package.
 
 import { existsSync } from "node:fs"
-import { dirname, join } from "node:path"
+import { dirname, join, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
 /**
@@ -17,26 +17,42 @@ import { fileURLToPath } from "node:url"
  * - `dist/extension.js`     -> `dist/daemon/main.js`
  * - `src/extension.ts`      -> `dist/daemon/main.js` when built (a published install)
  * - `src/extension.ts` only -> `src/daemon/main.ts` (a checkout, run with the flag)
+ *
+ * In a checkout the SOURCE wins even when `dist/` exists. `dist/` is gitignored and rebuilt only
+ * by `pretest`/`prepublishOnly`, so editing `src/daemon/*` without rebuilding would otherwise run
+ * the previous build - with an unchanged `API_VERSION`, so nothing detects the mismatch and the
+ * only symptom is a fix that appears not to work. A published install has no source to prefer.
  */
 export function resolveDaemonScript(moduleUrl: string | URL, exists: (path: string) => boolean = existsSync): string {
 	const here = fileURLToPath(moduleUrl)
 	const dir = dirname(here)
 	const root = dirname(dir)
 	const compiled = here.endsWith(".js")
+	// A dependency install is the only place `dist/` is the authority; everything else is a
+	// checkout someone is editing.
+	const installed = here.split(sep).includes("node_modules")
+	const built = join(root, "dist", "daemon", "main.js")
+	const source = join(dir, "daemon", "main.ts")
 	const candidates = compiled
 		? [
 				// dist/extension.js -> dist/daemon/main.js
 				join(dir, "daemon", "main.js"),
-				join(root, "dist", "daemon", "main.js"),
-				join(dir, "daemon", "main.ts"),
-			]
-		: [
-				// src/extension.ts -> the build, when the package was published
-				join(root, "dist", "daemon", "main.js"),
-				join(dir, "daemon", "main.js"),
-				// a checkout without a build
-				join(dir, "daemon", "main.ts"),
+				built,
+				source,
 			]
+		: installed
+			? [
+					// src/extension.ts inside node_modules: the compiled daemon, or nothing
+					built,
+					join(dir, "daemon", "main.js"),
+					source,
+				]
+			: [
+					// a checkout: what the editor has, not what the last build left behind
+					source,
+					built,
+					join(dir, "daemon", "main.js"),
+				]
 	for (const candidate of candidates) {
 		if (exists(candidate)) return candidate
 	}