ccdeck 3.32.1 → 3.33.0

package/src/server/lan-socket.mjs

@@ -27,7 +27,7 @@ import { inviteProof, inviteProofBack } from "./lan-invite.mjs";
 // The line both halves speak — the reader, the writer, the cap on a frame and
 // the deadline on a handshake — is lan-lines.mjs's. Re-exported, so what
 // imports it from here still does.
-import { frameReader, sendFrame, HANDSHAKE_MS } from "./lan-lines.mjs";
+import { frameReader, sendFrame, HANDSHAKE_MS, MAX_FRAME_BYTES } from "./lan-lines.mjs";
 export { frameReader, sendFrame, HANDSHAKE_MS, MAX_FRAME_BYTES } from "./lan-lines.mjs";
 // The calling half — dialling, proving, and reading a refusal — is
 // lan-call.mjs's. Re-exported, so what dials through this file still does.
@@ -84,6 +84,32 @@ export const MAX_SOCKETS_PER_HOST = 4;
  */
 export const IDLE_MS = 30_000;
 
+/**
+ * How many questions from one caller may wait behind the one being answered
+ * (#1739).
+ *
+ * A round asks one question and reads its answer before it asks the next —
+ * askOver in lan-engine.mjs — so a deck of any version never has a frame
+ * waiting here at all. The listener used to start its handler for every frame
+ * in a chunk at once, and a paired caller pipelining thousands of `manifest`
+ * questions had every answer built and queued in this process. Four is slack,
+ * not a queue: past it the caller is not asking the way any deck asks, and the
+ * connection is refused.
+ */
+export const MAX_WAITING_FRAMES = 4;
+
+/**
+ * The most answers a caller may leave unread before its connection is let go
+ * (#1739).
+ *
+ * An answer is one frame, at most MAX_FRAME_BYTES, and a round reads each one
+ * before it asks again — so even on a slow link one frame is the most an
+ * honest caller has sitting in this process's buffer. Four of them unread is a
+ * caller that has stopped reading, and every answer after that would be held
+ * here, in memory, for as long as it cared to keep asking.
+ */
+export const MAX_UNREAD_BYTES = 4 * MAX_FRAME_BYTES;
+
 /**
  * The answering half.
  *
@@ -170,6 +196,10 @@ export function createSyncServer({
   let server = null;
   let cancelStart = null;
   const live = new Set();
+  /** The challenge each live connection was sent. A caller holding this deck's
+   *  own key is answered (see auth), and this is how the deck tells its own
+   *  listener answering it from another machine that holds the same key. */
+  const challenges = new Set();
 
   /** Which host a socket came from, in one spelling. Node reports an IPv4 peer
    *  on a dual-stack listener as `::ffff:127.0.0.1`, and two spellings of one
@@ -242,6 +272,12 @@ export function createSyncServer({
      *  this end did. */
     const sealedChannel = () =>
       (sealsFrames(myChallenge) && sealsFrames(theirChallenge) ? frameChannel(key, "listener") : null);
+    /** Frames from the authenticated caller waiting behind the one being
+     *  answered, and whether one is — see MAX_WAITING_FRAMES. Only a handler
+     *  that returns a promise holds the line; one that answers there and then
+     *  is done before the next frame is read, as it always was. */
+    const waiting = [];
+    let answering = false;
 
     // Armed before the first byte is read, and cleared only by a completed
     // handshake. A socket that connects and says nothing is the cheapest
@@ -249,7 +285,8 @@ export function createSyncServer({
     const deadline = setTimeout(() => { if (!authed) sock.destroy(); }, handshakeMs);
     deadline.unref?.();
 
-    const done = () => { clearTimeout(deadline); live.delete(sock); };
+    challenges.add(myChallenge);
+    const done = () => { clearTimeout(deadline); live.delete(sock); challenges.delete(myChallenge); };
     sock.on("close", done);
     sock.on("error", err => { done(); onError?.("peer", err); });
 
@@ -391,6 +428,16 @@ export function createSyncServer({
       // was made when this socket opened and has never been sent before.
       if (!proofOk(want, msg.proof)) return refuse("bad proof");
 
+      // A CALLER HOLDING THIS DECK'S OWN KEY, which the proof above just
+      // showed. A deck that hears its own fingerprint from another process
+      // dials the address the beacon named to find out whether another machine
+      // really holds its key (see idClash in lan-engine.mjs), and this is the
+      // answer: our proof back, which only a holder of the key can make, and
+      // nothing more. Never a request to accept — that would pin this deck's
+      // own key — and nothing is served, because every handler asks the
+      // trusted list and this deck's own fingerprint is never on it.
+      if (peerFp === fp) { welcome({}); return; }
+
       // WHO IS THIS, and it is the only question left. The handshake proves
       // they hold the key they claimed; the trusted list says whether anybody
       // here ever agreed to talk to it.
@@ -495,6 +542,48 @@ export function createSyncServer({
       welcome({});
     };
 
+    /** Hand one authenticated frame to the handler, and the next waiting one
+     *  once it is done. A throw ends the connection, as it did when the frame
+     *  reader called the handler itself; so does a promise that rejects, which
+     *  nothing used to catch. */
+    const answer = frame => {
+      let out;
+      try { out = handlers?.(frame, answerCtx()); }
+      catch (err) { if (!refused) refuse("bad frame", err); return; }
+      if (!out || typeof out.then !== "function") return answerNext();
+      answering = true;
+      out.then(null, err => { if (!refused) refuse("bad frame", err); })
+        .finally(() => { answering = false; answerNext(); });
+    };
+    const answerNext = () => {
+      if (refused || sock.destroyed || !waiting.length) { waiting.length = 0; return; }
+      answer(waiting.shift());
+    };
+    /** What the handler is handed with each frame. */
+    const answerCtx = () => ({
+      sock, peerFp, key, sealed: !!chan,
+      // Where this deck dials the caller BACK. A deck that only ever calls in
+      // is one this deck holds no address for, so it could receive nothing —
+      // accounts move only toward the deck that dials (see roundWith). The
+      // address the caller connected from, and the port it said it listens
+      // on, are a dialable pair the engine can add so the next round reaches
+      // it. `peerAddr` is the source of this very connection; `peerPort` came
+      // from the hello, not the ephemeral source port.
+      peerAddr: from(sock),
+      peerPort,
+      send: obj => {
+        sendFrame(sock, chan ? chan.wrap(obj) : obj);
+        // AND NOT INTO MEMORY FOR A CALLER THAT DOES NOT READ (#1739). The
+        // write never looked at what was already queued; past
+        // MAX_UNREAD_BYTES the caller has stopped reading, and it is let go
+        // rather than answered into this process's heap.
+        if (!sock.destroyed && sock.writableLength > MAX_UNREAD_BYTES) {
+          onError?.("frame", new Error("answers left unread"));
+          sock.destroy();
+        }
+      },
+    });
+
     sock.on("data", frameReader(msg => {
       // NOTHING AFTER A REFUSAL. The reader hands over every frame in a chunk,
       // and `refuse` destroys the socket without stopping it. So a `hello`
@@ -533,19 +622,16 @@ export function createSyncServer({
       // as it stands instead; that fallback would be the downgrade.
       const frame = chan ? chan.unwrap(msg) : msg;
       if (!frame) return refuse("a sealed frame did not open");
-      handlers?.(frame, {
-        sock, peerFp, key, sealed: !!chan,
-        // Where this deck dials the caller BACK. A deck that only ever calls in
-        // is one this deck holds no address for, so it could receive nothing —
-        // accounts move only toward the deck that dials (see roundWith). The
-        // address the caller connected from, and the port it said it listens
-        // on, are a dialable pair the engine can add so the next round reaches
-        // it. `peerAddr` is the source of this very connection; `peerPort` came
-        // from the hello, not the ephemeral source port.
-        peerAddr: from(sock),
-        peerPort,
-        send: obj => sendFrame(sock, chan ? chan.wrap(obj) : obj),
-      });
+      // ONE QUESTION AT A TIME (#1739). Opened as it arrives — the seal counts
+      // frames in the order they came — and answered in that order, each after
+      // the last. A caller with more than a few waiting is not asking the way a
+      // round does; see MAX_WAITING_FRAMES.
+      if (answering) {
+        if (waiting.length >= MAX_WAITING_FRAMES) return refuse("too many questions at once");
+        waiting.push(frame);
+        return;
+      }
+      answer(frame);
     }, refuse));
   };
 
@@ -612,10 +698,14 @@ export function createSyncServer({
       catch (err) { finish(reject, err); }
     }),
     port: () => server?.address()?.port ?? null,
+    /** Whether this listener made `challenge` for a connection still open —
+     *  true when the deck at the other end of a dial is this one. */
+    issued: challenge => typeof challenge === "string" && challenges.has(challenge),
     stop() {
       cancelStart?.();
       for (const s of live) s.destroy();
       live.clear();
+      challenges.clear();
       try { server?.close(); } catch { /* not listening */ }
       server = null;
     },

package/src/server/lan-sync.mjs

@@ -317,8 +317,9 @@ export function readBeacon(buf, { maxBytes = MAX_BEACON_BYTES } = {}) {
  * A reason rather than a boolean, because each answer asks for something
  * different: a packet that is not a beacon, this deck's own echo, or another
  * deck on this computer is nothing to act on; a deck wearing this one's key
- * (`id-clash`) is a key to replace; a paired deck is a peer to note; and a
- * stranger is a row somebody can accept.
+ * (`id-clash`) is a claim to check, and a key to replace if it holds (see
+ * idClash in lan-engine.mjs); a paired deck is a peer to note; and a stranger
+ * is a row somebody can accept.
  *
  * Self-recognition is by fingerprint, not by address: a deck hears its own
  * broadcast on every interface it owns, and filtering by address would need a
@@ -390,6 +391,13 @@ export function trustedPeer(trusted, fp) {
  * different deck wearing the name — and 48 bits of fingerprint is far past
  * accident, so it is somebody trying. The old entry stands and the caller is
  * told nothing changed.
+ *
+ * `auto` SAYS A SWITCH MADE THE PIN, not a person — the accept switch pressing
+ * accept for the owner. A pin that says so may take what this deck shares and
+ * may not place logins here: see roundWith in lan-engine.mjs. A person's pin
+ * of the same key takes the mark away, because pressing accept, or pairing by
+ * invite, is the choice the switch only stood in for; a switch never puts it
+ * back on a pin a person made.
  */
 export function addTrusted(trusted, entry) {
   const list = Array.isArray(trusted) ? trusted : [];
@@ -397,8 +405,13 @@ export function addTrusted(trusted, entry) {
   const had = trustedPeer(list, entry.fp);
   if (had) {
     if (had.pub !== entry.pub) return { list, added: false };
+    const chosen = had.auto && entry.auto !== true;
     return {
-      list: list.map(t => (t.fp === entry.fp ? { ...t, name: entry.name ?? t.name } : t)),
+      list: list.map(t => {
+        if (t.fp !== entry.fp) return t;
+        const { auto: _auto, ...kept } = t;
+        return { ...(chosen ? kept : t), name: entry.name ?? t.name };
+      }),
       added: false,
     };
   }
@@ -406,7 +419,8 @@ export function addTrusted(trusted, entry) {
   // was already trusted keeps whatever date it had, and one pinned before this
   // field existed keeps having none rather than being given today's.
   const at = Number.isFinite(entry.at) && entry.at > 0 ? { at: entry.at } : {};
-  return { list: [...list, { fp: entry.fp, pub: entry.pub, name: entry.name ?? "", ...at }], added: true };
+  const auto = entry.auto === true ? { auto: true } : {};
+  return { list: [...list, { fp: entry.fp, pub: entry.pub, name: entry.name ?? "", ...at, ...auto }], added: true };
 }
 
 /** Take one back out. Unpairing stops what has not happened yet and takes back

package/src/server/lifecycle.mjs

@@ -14,7 +14,7 @@
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createActivity } from "./activity.mjs";
-import { AWAY_BOOT_GRACE_MS, AWAY_RECHECK_MS, AWAY_TICK_MS, awayGate, awayUpdateStep } from "./auto-update.mjs";
+import { AWAY_BOOT_GRACE_MS, AWAY_RECHECK_MS, AWAY_TICK_MS, awayGate, awayUpdateStep, turnsQuiet } from "./auto-update.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { logWritableNow } from "./event-log.mjs";
 import { readBody, send } from "./http-io.mjs";
@@ -165,6 +165,14 @@ async function handleUpgrade(_req, res) {
 // `npx -y <spec>@latest` instead of re-running the files already here. Granted
 // only where that is genuinely how this copy updates — the mode is decided from
 // the install on disk, never from the request.
+//
+// `{ whenIdle: true }` is the page's automatic restart, which is granted only
+// while no turn is running here (turnsQuiet). The page counts its idle stretch
+// from its own graph, and a paused canvas stops applying events, so a turn sent
+// from the terminal was invisible to it and the deck restarted under the agent
+// (#1764). This process hears every turn whatever a page is doing, and it is
+// asked at the moment the restart would happen. A person's press does not send
+// it: "Restart anyway" is theirs to make.
 async function handleRestart(req, res) {
   if (!_onRestart) return send(res, 501, { ok: false, reason: "unsupervised" });
   // Enforced here and not only in the UI. Under --no-persist a restart destroys
@@ -178,9 +186,14 @@ async function handleRestart(req, res) {
   if (!canRestartNow()) return send(res, 409, { ok: false, reason: "log_unwritable" });
 
   let wantUpgrade = false;
+  let whenIdle = false;
   if (req.method === "POST") {
     const body = await readBody(req, res).catch(() => null);
-    try { wantUpgrade = JSON.parse(body ?? "")?.upgrade === true; } catch { /* a plain restart */ }
+    try {
+      const ask = JSON.parse(body ?? "");
+      wantUpgrade = ask?.upgrade === true;
+      whenIdle = ask?.whenIdle === true;
+    } catch { /* a plain restart */ }
   }
   let mode = null;
   if (wantUpgrade) {
@@ -194,6 +207,12 @@ async function handleRestart(req, res) {
   }
 
   if (_restarting) return send(res, 202, { ok: true, already: true });
+  if (whenIdle) {
+    const now = Date.now();
+    if (!turnsQuiet({ busy: activity.busy(now), quietMs: activity.quietMs(now) })) {
+      return send(res, 409, { ok: false, reason: "busy" });
+    }
+  }
   _restarting = true;
   // Accepted either way — the ask is good and the launcher holds on to it — but
   // the two are not the same event and answering 200 to both would be this

package/src/server/live-radio-mix.mjs

@@ -19,7 +19,8 @@ function currentLiveVideo(html) {
 
 export async function fetchLiveRadioMix({ fetchImpl } = {}) {
   const now = Date.now();
-  if (cache && now - cacheAt < cacheTtl) return cache;
+  // The stamp, not the value: a miss is remembered too, as null.
+  if (cacheAt && now - cacheAt < cacheTtl) return cache;
   if (inflight) return inflight;
   const get = fetchImpl ?? fetch;
   inflight = (async () => {

package/src/server/log-replay.mjs

@@ -11,7 +11,7 @@ import { existsSync } from "node:fs";
 import { PRODUCT } from "./brand.mjs";
 import { codexCwdInWorkspace } from "./log-election.mjs";
 import { linesFromEnd, linesFromStart } from "./log-tail.mjs";
-import { ENVELOPE_CHARS, MAX_BUFFER, MAX_BUFFER_CHARS, payloadChars } from "./ring-bounds.mjs";
+import { ENVELOPE_CHARS, MAX_BUFFER, MAX_BUFFER_CHARS, MAX_RING_ENTRIES, isEnrichment, payloadChars } from "./ring-bounds.mjs";
 // event-pipeline.mjs's pushEvent, reached without importing it — see
 // event-sink.mjs.
 import { pushEvent } from "./event-sink.mjs";
@@ -151,28 +151,56 @@ export function replayScope(workspace, platform = process.platform, providers =
   };
 }
 
+/**
+ * The ring's three bounds, counted the way the ring counts them, for a reader
+ * that stages the log newest-first and has to know when to stop.
+ *
+ * MAX_BUFFER is HOOK events since #1032: the enrichment interleaved among them
+ * (LAST_VALUE_WINS) rides free, bounded only by MAX_RING_ENTRIES and
+ * MAX_BUFFER_CHARS. This used to count every line toward MAX_BUFFER, and at the
+ * ~1.6 enrichment lines a real deck logs per hook event that stopped the boot
+ * replay with about a third of the ring's window rebuilt (#1750). `add` stages
+ * one payload and answers whether the ring is now full.
+ */
+function ringBudget(maxEvents, maxEntries, maxChars) {
+  let hookEvents = 0;
+  let entries = 0;
+  let chars = 0;
+  const full = () => hookEvents >= maxEvents || entries >= maxEntries || chars >= maxChars;
+  return {
+    full,
+    add(payload) {
+      entries++;
+      if (!isEnrichment(payload)) hookEvents++;
+      chars += ENVELOPE_CHARS + payloadChars(payload);
+      return full();
+    },
+  };
+}
+
 /**
  * Can this log fill the ring on its own?
  *
  * Read from the END and bounded by the ring, so the answer costs at most one
  * ring's worth of parsing however large the file is — and on a full log it
- * stops within the first few hundred lines. Deliberately UNSCOPED: the number
+ * stops within the first few thousand lines. Deliberately UNSCOPED: the number
  * it returns is an upper bound on what any workspace predicate will admit, so
  * `false` is a certainty that the archive is needed while `true` is only the
  * absence of evidence that it is. See the order-dependent branch of replayLog
  * for why that asymmetry is the right way round.
+ *
+ * Counted by `ringBudget`, the same rule the unscoped replay stops by, so
+ * "fills the ring" means MAX_BUFFER hook events and not MAX_BUFFER lines of
+ * which most are enrichment (#1750).
  */
-async function fillsRing(filePath, maxEvents, maxChars) {
-  let n = 0;
-  let chars = 0;
+async function fillsRing(filePath, maxEvents, maxEntries, maxChars) {
+  const budget = ringBudget(maxEvents, maxEntries, maxChars);
   for await (const line of linesFromEnd(filePath)) {
     if (!line) continue;
     let evt;
     try { evt = JSON.parse(line); } catch { continue; }
     if (!evt || typeof evt !== "object" || !evt.payload) continue;
-    n++;
-    chars += ENVELOPE_CHARS + payloadChars(evt.payload);
-    if (n >= maxEvents || chars >= maxChars) return true;
+    if (budget.add(evt.payload)) return true;
   }
   return false;
 }
@@ -225,11 +253,15 @@ async function fillsRing(filePath, maxEvents, maxChars) {
  * feeding the eviction loop, on the critical path of a boot, every time.
  *
  * So the lines arrive newest-first and the loop stops the moment the ring is
- * full, which makes the cost a property of MAX_BUFFER rather than of how long
- * the user has been running the deck. Nothing is lost by it: what a forward
- * replay left in the ring was always the NEWEST admitted events that fit, and
- * that is exactly the set this collects. A young log — too few events to fill
- * the ring — is read to its start, and costs what it always did.
+ * full, which makes the cost a property of the ring's bounds rather than of how
+ * long the user has been running the deck. Nothing is lost by it: what a
+ * forward replay left in the ring was always the NEWEST admitted events that
+ * fit, and that is the set this collects — provided "full" is counted the way
+ * the ring counts it. Since #1032 that is MAX_BUFFER hook events with their
+ * enrichment riding along, and counting every line toward MAX_BUFFER instead
+ * rebuilt about a third of the window (#1750); see ringBudget. A young log —
+ * too few events to fill the ring — is read to its start, and costs what it
+ * always did.
  *
  * The order of the pushes is still oldest-first. `seq` is assigned by pushEvent
  * in the order it is called, and a ring numbered backwards would hand every
@@ -245,12 +277,12 @@ async function fillsRing(filePath, maxEvents, maxChars) {
  * that case cheap needs an index of where a workspace's lines are, which is a
  * different change from this one.
  */
-/* Exported for the suite, with both ceilings as parameters. The byte budget is
+/* Exported for the suite, with the ceilings as parameters. The byte budget is
  * 128 MiB, so a test that wanted to reach it honestly would have to write 128
  * MiB — which is why the count bound was the only one anything pinned, and why
- * the byte bound was the one that broke. Production passes neither argument. */
+ * the byte bound was the one that broke. Production passes none of them. */
 export async function replayLog(filePath, workspace = "", {
-  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS, providers = null,
+  maxEvents = MAX_BUFFER, maxEntries = MAX_RING_ENTRIES, maxChars = MAX_BUFFER_CHARS, providers = null,
 } = {}) {
   // THE ARCHIVE IS PART OF THE HISTORY, and for two years nothing read it.
   // `maybeRotatePersistFile` renames events.jsonl to events.jsonl.1 at 50 MB;
@@ -311,7 +343,7 @@ export async function replayLog(filePath, workspace = "", {
     // what it does today. Nothing regresses; the case a rotation creates, where
     // the live log holds a handful of lines, is the one that is fixed.
     const files = [];
-    if (archiveThere && !(liveThere && await fillsRing(filePath, maxEvents, maxChars))) files.push(archivePath);
+    if (archiveThere && !(liveThere && await fillsRing(filePath, maxEvents, maxEntries, maxChars))) files.push(archivePath);
     if (liveThere) files.push(filePath);
     for (const file of files) {
       for await (const line of linesFromStart(file)) {
@@ -324,8 +356,8 @@ export async function replayLog(filePath, workspace = "", {
     }
   } else {
     // Newest first, so this is filled back to front and then walked in reverse
-    // to push. Bounded by BOTH of the ring's limits, which is what makes the
-    // memory here a property of the ring rather than of the file.
+    // to push. Bounded by ALL of the ring's limits (see ringBudget), which is
+    // what makes the memory here a property of the ring rather than of the file.
     //
     // The count alone was not enough, and the comment that used to say it was
     // predates #625. Eviction is the only thing that applies MAX_BUFFER_CHARS,
@@ -339,24 +371,23 @@ export async function replayLog(filePath, workspace = "", {
     // best-effort and its failure is only logged, and the rotation's own note
     // in event-log.mjs records logs reaching gigabytes.
     const newestFirst = [];
-    let stagedChars = 0;
+    const budget = ringBudget(maxEvents, maxEntries, maxChars);
     // Newest generation first. The second pass runs only if the first stopped
     // because it ran out of FILE rather than because it reached a bound, which
     // is the "cannot fill the ring" test stated exactly and for free — and it
     // is also why a full live log never opens the archive at all.
     for (const file of liveThere ? [filePath, archivePath] : [archivePath]) {
       if (!existsSync(file)) continue;
-      if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
+      if (budget.full()) break;
       for await (const line of linesFromEnd(file)) {
         if (!line) continue;
         const evt = parse(line);
         if (!usable(evt) || !admits(evt.payload)) continue;
         newestFirst.push(evt);
-        stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
         // Everything older than this would be evicted by the events already held,
         // so reading further is work whose only result is throwing it away.
-        // Either limit reaching its ceiling means exactly that.
-        if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
+        // Any of the three limits reaching its ceiling means exactly that.
+        if (budget.add(evt.payload)) break;
       }
     }
     for (let i = newestFirst.length - 1; i >= 0; i--) replay(newestFirst[i]);

package/src/server/login-service.mjs

@@ -359,6 +359,30 @@ export function scopeEnv(env = process.env) {
   );
 }
 
+/**
+ * The PATH for the login item's job (#1777).
+ *
+ * The service manager's, not the shell's, is what a login item gets: launchd's
+ * is /usr/bin:/bin:/usr/sbin:/sbin, and the systemd user manager's names no
+ * nvm, fnm or Volta directory. A deck started there could not find the npm its
+ * own update runs, or the node a `#!/usr/bin/env node` claude asks for — on
+ * exactly the installs where the prefix is the user's own, so the update is
+ * offered and then fails with `spawn npm ENOENT` on every retry.
+ *
+ * Node's own directory first, since npm, npx and a global claude sit beside it
+ * on every layout that installs them together; then the installing shell's
+ * PATH in its own order, each directory once. Empty entries are dropped: a
+ * shell reads one as the current directory, and a login job has no business
+ * resolving programs out of wherever it happened to start.
+ */
+export function jobPath({ execPath, path = "", platform = process.platform } = {}) {
+  const sep = platform === "win32" ? ";" : ":";
+  const exe = String(execPath ?? "");
+  const node = exe ? (platform === "win32" ? winPath : posixPath).dirname(exe) : "";
+  const dirs = [node === "." ? "" : node, ...String(path ?? "").split(sep)].filter(d => d !== "");
+  return [...new Set(dirs)].join(sep);
+}
+
 /**
  * Write the login item and register it.
  *
@@ -373,7 +397,13 @@ export function installService({
   execPath = process.execPath,
   script,
   logPath,
-  args = ["--no-open"],
+  // `--at-login` because registering the job also STARTS it, on Linux and
+  // macOS — `enable --now`, and RunAtLoad under `launchctl load` — and a deck
+  // of the default shape that finds a `--workspace` or `--no-persist` deck
+  // running replaces it: the newest start wins. So the first start's own offer
+  // stopped the deck the user had just launched (#1778). The marker is what
+  // lets secondStart tell a start nobody typed from one somebody did.
+  args = ["--no-open", "--at-login"],
   // Extra variables for the JOB's environment, which is not this process's.
   //
   // A login item runs in the session the service manager builds, not in the
@@ -422,9 +452,14 @@ export function installService({
       return { ok: true, path: `Task Scheduler ${GLYPH_ARROW} ${SERVICE_LABEL}`, how: "schtasks" };
     }
 
+    // PATH beside the scope directories rather than among them: it is not
+    // which deck this is but whether the deck can find its own tools, so it is
+    // in every job — and a caller's own serviceEnv can still name one.
+    const PATH = jobPath({ execPath, path: env?.PATH, platform });
+    const jobEnv = { ...(PATH ? { PATH } : {}), ...serviceEnv };
     const body = platform === "darwin"
-      ? plistFor({ execPath, script, logPath, args, env: serviceEnv })
-      : unitFor({ execPath, script, logPath, args, env: serviceEnv, product });
+      ? plistFor({ execPath, script, logPath, args, env: jobEnv })
+      : unitFor({ execPath, script, logPath, args, env: jobEnv, product });
     fs.mkdirSync(dirOf(path), { recursive: true });
     fs.writeFileSync(path, body, { mode: 0o644 });
     const cmd = registerCommand(platform, path);

package/src/server/metrics-run.mjs

@@ -66,14 +66,16 @@ const C_LOCALE = { LC_ALL: "", LC_NUMERIC: "C" };
 
 /** Run a command and resolve its stdout, or null. Never rejects, never inherits
  *  a shell, never inherits a locale, and is killed rather than allowed to hang
- *  the sampler. */
-export function run(file, args, timeoutMs = 2_000) {
+ *  the sampler. `env` is what the child starts from — the deck's own, unless a
+ *  command needs more than that, as Tailscale's CLI does (cliEnv in
+ *  tailscale.mjs) — and the forced number format goes over it either way. */
+export function run(file, args, timeoutMs = 2_000, env = process.env) {
   return new Promise(resolve => {
     let child;
     try {
       child = spawn(file, args, {
         windowsHide: true,
-        env: { ...process.env, ...C_LOCALE },
+        env: { ...env, ...C_LOCALE },
         // stderr is PIPED AND NEVER READ, which is a deadlock waiting for a
         // chatty child: a pipe nobody drains fills at 64 KB and the writer
         // blocks there until this function's own deadline kills it. Nothing

package/src/server/network-sampler.mjs

@@ -18,6 +18,7 @@ import {
   classifyRoute, parseNetstatE, parseNetstatIbn, parseProcNetDev, rateBetween,
   routeIfaceDarwin, routeIfaceLinux, routeLabel, tailscaleExitFromStatus,
 } from "./network-metrics.mjs";
+import { cliEnv, tailscaleCandidates } from "./tailscale.mjs";
 
 // ── the network ────────────────────────────────────────────────────────────
 //
@@ -136,6 +137,16 @@ function connectMs(address, port = API_PORT, timeoutMs = CONNECT_TIMEOUT_MS) {
   });
 }
 
+/** `tailscale status --json` as an object, or null for anything that is not
+ *  one: nothing on stdout, the macOS GUI's message, a version warning. */
+function statusDocument(out) {
+  if (typeof out !== "string") return null;
+  try {
+    const doc = JSON.parse(out);
+    return doc && typeof doc === "object" ? doc : null;
+  } catch { return null; }
+}
+
 /** Which way traffic to `address` leaves, and — for a Tailscale exit node —
  *  through which machine and whether through a relay. */
 async function readRoute(address, platform, runner) {
@@ -147,8 +158,20 @@ async function readRoute(address, platform, runner) {
   // Tailscale on a Mac is a utun like every other VPN there, so the question is
   // asked of any tunnel rather than only of one named tailscale0. A machine
   // without the CLI answers null and keeps the generic label.
-  const exit = tailscaleExitFromStatus(await runner("tailscale", ["status", "--json"], 3_000));
-  if (exit) return { kind: "tailscale-exit", iface, ...exit };
+  //
+  // WHERE THE CLI IS AND HOW IT IS RUN are tailscale.mjs's answers, not PATH's
+  // (#1772). This asked a bare `tailscale`, and the Mac app keeps its CLI in
+  // the bundle and puts nothing on PATH unless its owner pressed "Install CLI"
+  // — and a deck started at login has launchd's PATH anyway. The bundle binary
+  // is also the GUI, which without cliEnv() prints a message and exits 0. So
+  // the candidates are tried in the LAN code's order, as a CLI, and the first
+  // one that answers with a status document is the one that is installed.
+  for (const file of tailscaleCandidates(platform)) {
+    const doc = statusDocument(await runner(file, ["status", "--json"], 3_000, cliEnv()));
+    if (!doc) continue;
+    const exit = tailscaleExitFromStatus(doc);
+    return exit ? { kind: "tailscale-exit", iface, ...exit } : kind;
+  }
   return kind;
 }
 

package/src/server/npm-upgrade.mjs

@@ -14,6 +14,7 @@ import { accessSync, constants as FS, unlinkSync, writeFileSync } from "node:fs"
 import { spawn } from "node:child_process";
 import { join, resolve } from "node:path";
 import { killTree, shimPath, spawnSpec } from "./exec.mjs";
+import { npmCliLaunch } from "./npx.mjs";
 import {
   frozenNameInstall, hostPackage, installedName, isGitCheckout, isNpxInstall,
   PUBLISHED_NAME, successorRoot, upgradeCommand, upgradeName,
@@ -61,7 +62,13 @@ const INSTALL_TIMEOUT_MS = 300_000; // a cold global install on a slow line
  */
 export function upgradeSpec(target, platform = process.platform, deps) {
   const args = ["install", "-g", `${target}@latest`, "--no-audit", "--no-fund", "--loglevel", "error"];
-  const file = platform === "win32" ? (shimPath("npm.cmd", deps) ?? "npm.cmd") : "npm";
+  // POSIX: the npm-cli.js beside this node, and the bare name only when there
+  // is none, because a deck started at login has no PATH that finds npm on a
+  // Homebrew or nvm install (#1777). See npmCliLaunch.
+  if (platform !== "win32") {
+    return { ...(npmCliLaunch(args, { platform, ...deps }) ?? spawnSpec("npm", args, platform)), plain: args };
+  }
+  const file = shimPath("npm.cmd", deps) ?? "npm.cmd";
   return { ...spawnSpec(file, args, platform), plain: args };
 }