@talotrace/connect 0.7.0 → 0.9.0

package/README.md

@@ -33,7 +33,9 @@ saying so. Ctrl-C ends a session at once; a killed one counts until its two-minu
 ## Stopping
 
 Ctrl-C, SIGTERM or a closed terminal stops it within 2 seconds and ends its session (`dev` may take up to 30 seconds:
-it releases the phone and closes a cloud workspace first). A second Ctrl-C stops it at once. The stdio MCP server stops when your agent closes it.
+it releases the phone and closes a cloud workspace first). A second Ctrl-C stops it at once, and the launcher sends SIGKILL if the binary has not stopped 5 seconds after the signal (`dev` announces its longer stop). The stdio MCP server stops when your agent closes it.
+
+The launcher runs the binary from a copy under your user cache directory (`~/Library/Caches/talotrace-connect/<version>/` on macOS), checked against the checksum published with the package, so unplugging the disk that holds npm's cache cannot hang it.
 
 If the binary stops responding (for example, the disk holding npm's cache was unplugged, which leaves a program unable
 to run its own code), the launcher stops it after 5 seconds and says so.
@@ -42,4 +44,4 @@ to run its own code), the launcher stops it after 5 seconds and says so.
 
 `0` done or stopped, `1` failure, `2` usage, `3` TaloTrace ended the session, `4` you ended it, `5` the session expired,
 `6` the relay refused its credential, `7` another `talotrace-connect` took the session over, `8` it did not finish
-stopping within its budget, `9` it stopped responding and the launcher stopped it.
+stopping within its budget, `9` it stopped responding and the launcher stopped it. A binary ended by a signal gives `128` plus the signal number.

package/bin/talotrace-connect.js

@@ -2,7 +2,10 @@
 'use strict';
 
 const { spawn } = require('node:child_process');
+const os = require('node:os');
 const { binaryPath } = require('../lib/resolve');
+const { verifiedCopy } = require('../lib/copy');
+const { KILL_AFTER_MS, killDelay } = require('../lib/escalate');
 const {
   ALIVE_ENV,
   ALIVE_FD,
@@ -14,7 +17,13 @@ const {
 
 let binary;
 try {
-  binary = binaryPath(process.platform, process.arch, require.resolve);
+  const source = binaryPath(process.platform, process.arch, require.resolve);
+  const platformKey = `${process.platform}-${process.arch}`;
+  const expected = require('../checksums.json')[platformKey];
+  if (!expected) {
+    throw new Error(`@talotrace/connect publishes no checksum for ${platformKey}`);
+  }
+  binary = verifiedCopy({ source, expected, version: require('../package.json').version });
 } catch (error) {
   console.error(error.message);
   process.exit(1);
@@ -27,13 +36,44 @@ const stdio = watched ? ['inherit', 'inherit', 'inherit', 'pipe'] : 'inherit';
 const env = watched ? { ...process.env, [ALIVE_ENV]: String(ALIVE_FD) } : process.env;
 const child = spawn(binary, process.argv.slice(2), { stdio, env });
 
-// The first signal is passed on and the binary stops within its own shutdown budget; a second one
-// kills it now.
+// The first signal is passed on and the binary stops within its own shutdown budget; SIGKILL follows
+// when it has not (lib/escalate.js), and a second signal kills it now. A terminal's Ctrl-C and hangup
+// already reach the binary (same process group), so with a terminal on stdin the launcher does not
+// send those two again: a repeat would be the binary's second signal and kill it mid-stop.
 let stopping = false;
+let stoppedAt = 0;
+let stopBudgetMs = 0; // what the binary says its stop may take, from its beats
+// Any of the three standard streams being a terminal means Ctrl-C and hangup reach the binary directly.
+// A binary run with all three redirected under a terminal's process group (a script) can still get its
+// Ctrl-C twice; the binary then takes the repeat as its second signal. That is the known limit.
+const onTerminal = [0, 1, 2].some((fd) => require('node:tty').isatty(fd));
+const reachedByTerminal = new Set(onTerminal ? ['SIGINT', 'SIGHUP'] : []);
+// Only `dev` (releasing a phone and a cloud workspace) may run past the 5 s backstop; any other
+// command is killed at 5 s whatever its beats announce (L41).
+const mayRunLong = process.argv[2] === 'dev';
+function killChild() {
+  child.kill('SIGKILL');
+}
+function escalate() {
+  const wait = killDelay(Date.now() - stoppedAt, stopBudgetMs);
+  if (wait <= 0) {
+    killChild();
+  } else {
+    setTimeout(escalate, wait).unref();
+  }
+}
 for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
   process.on(signal, () => {
-    child.kill(stopping ? 'SIGKILL' : signal);
+    if (stopping) {
+      killChild();
+      return;
+    }
     stopping = true;
+    stoppedAt = Date.now();
+    if (!reachedByTerminal.has(signal)) {
+      child.kill(signal);
+    }
+    setTimeout(escalate, KILL_AFTER_MS).unref();
   });
 }
 
@@ -41,7 +81,10 @@ let unresponsive = false;
 let looking = null;
 if (watched) {
   const watch = aliveWatch(Date.now);
-  child.stdio[ALIVE_FD].on('data', () => watch.beat());
+  child.stdio[ALIVE_FD].on('data', (beats) => {
+    watch.beat();
+    if (mayRunLong) stopBudgetMs = Math.max(stopBudgetMs, beats[beats.length - 1] * 1000); // 0 until a stop is under way
+  });
   child.stdio[ALIVE_FD].on('error', () => {}); // the child exiting closes it; 'exit' reports that
   looking = setInterval(() => {
     if (watch.look()) {
@@ -61,10 +104,8 @@ child.on('exit', (code, signal) => {
   clearInterval(looking);
   if (unresponsive) {
     process.exit(EXIT_UNRESPONSIVE);
-  } else if (signal) {
-    process.removeAllListeners(signal); // so the signal ends this process as it ended the child
-    process.kill(process.pid, signal);
   } else {
-    process.exit(code ?? 1);
+    // The child's own code; a child ended by a signal gives the shell's 128 + signal number.
+    process.exit(code ?? 128 + (os.constants.signals[signal] ?? 1));
   }
 });

package/checksums.json

@@ -0,0 +1,7 @@
+{
+  "darwin-arm64": "81eaaa7dc30769b7aca5f34353e5008b355697745cf8518ba542c3afc30acf0e",
+  "darwin-x64": "bb33f6c29b3318345ff323b548fe5de95566d250ecdb9ff2d847e1e4c5e80686",
+  "linux-arm64": "4b9a07202940f75e1f0fed9f49ac43019261268248df2d21f46f21bfed43f2af",
+  "linux-x64": "05e1b04182fcf07d64be493a06c93b6d8b4e6a99fa3c5716ec0cf84ecbf57163",
+  "win32-x64": "a46b77206c1ff061c2d71aa0bacd9a42ad8dcbac66095cdbc844f9b02917094c"
+}

package/lib/copy.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// The binary runs from a copy on the system disk. npx and npm keep packages in a cache that may live on
+// an external disk, and a program whose file sits on a volume that went away spins at full CPU and
+// ignores signals (31 Oct 2026: two clients ran for 8 hours after such a disk dropped out). The copy is
+// checked against the checksum this package was published with, so a half-written or tampered file is
+// never run.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CACHE_DIR_NAME = 'talotrace-connect';
+
+/** The per-user cache directory for this OS, built from the home directory (never npm's cache). */
+function userCacheDir(platform, env, home) {
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Caches');
+  }
+  if (platform === 'win32') {
+    return env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  }
+  return env.XDG_CACHE_HOME || path.join(home, '.cache');
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+/**
+ * The path of a checksum-verified copy of `source` under `<user cache>/talotrace-connect/<version>/`,
+ * made when it is missing or does not match. `expected` is the checksum published for this platform.
+ * The copy is written under a temporary name and renamed, so concurrent launchers never see a partial file.
+ */
+function verifiedCopy({ source, expected, version, platform = process.platform, env = process.env, home = os.homedir() }) {
+  if (sha256(source) !== expected) {
+    throw new Error(
+      `${source} does not match the checksum published with @talotrace/connect ${version}; ` +
+        'reinstall it (npm cache clean --force, then run the command again).',
+    );
+  }
+  const dir = path.join(userCacheDir(platform, env, home), CACHE_DIR_NAME, version);
+  const target = path.join(dir, path.basename(source));
+  if (fs.existsSync(target) && sha256(target) === expected) {
+    return target;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const partial = `${target}.${process.pid}.tmp`;
+  try {
+    fs.copyFileSync(source, partial);
+    fs.chmodSync(partial, 0o755);
+    if (sha256(partial) !== expected) {
+      throw new Error(`the copy of ${source} under ${dir} does not match its checksum; is the disk full?`);
+    }
+    fs.renameSync(partial, target);
+  } finally {
+    fs.rmSync(partial, { force: true });
+  }
+  return target;
+}
+
+module.exports = { CACHE_DIR_NAME, userCacheDir, verifiedCopy };

package/lib/escalate.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// When the launcher gives up waiting for a stopped binary and sends SIGKILL. A binary that ignores
+// SIGTERM (or whose program file went away) must not outlive its launcher's stop by more than this.
+
+/** SIGKILL follows the forwarded signal after this long. */
+const KILL_AFTER_MS = 5000;
+/** A binary that announced a longer stop (`dev` releasing a phone) is given that, plus this. */
+const ANNOUNCED_SLACK_MS = 1000;
+
+/**
+ * Milliseconds still to wait before SIGKILL, `sinceSignalMs` after the signal, when the binary has
+ * announced a stop budget of `announcedMs` (0 when it has not). 0 or less means kill now.
+ */
+function killDelay(sinceSignalMs, announcedMs) {
+  const allowed = announcedMs > 0 ? Math.max(KILL_AFTER_MS, announcedMs + ANNOUNCED_SLACK_MS) : KILL_AFTER_MS;
+  return allowed - sinceSignalMs;
+}
+
+module.exports = { KILL_AFTER_MS, ANNOUNCED_SLACK_MS, killDelay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talotrace/connect",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "TaloTrace Connect: the TaloTrace MCP server for your coding agent, with a tunnel to the app on your laptop.",
   "license": "UNLICENSED",
   "bin": {
@@ -9,7 +9,8 @@
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "checksums.json"
   ],
   "engines": {
     "node": ">=18"
@@ -18,10 +19,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@talotrace/connect-darwin-arm64": "0.7.0",
-    "@talotrace/connect-darwin-x64": "0.7.0",
-    "@talotrace/connect-linux-arm64": "0.7.0",
-    "@talotrace/connect-linux-x64": "0.7.0",
-    "@talotrace/connect-win32-x64": "0.7.0"
+    "@talotrace/connect-darwin-arm64": "0.9.0",
+    "@talotrace/connect-darwin-x64": "0.9.0",
+    "@talotrace/connect-linux-arm64": "0.9.0",
+    "@talotrace/connect-linux-x64": "0.9.0",
+    "@talotrace/connect-win32-x64": "0.9.0"
   }
 }