@dmsdc-ai/aigentry-telepty 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [0.4.3] - 2026-05-23
+
+### Fixed
+
+- **telepty#15** — Daemon version mismatch auto-restart + port-owner
+  fallback + banner-to-stderr (root-cause fix for task #400).
+  - All five daemon-related banners in `cli.js` (lines 429, 585, 592,
+    594, 600) now emit to `process.stderr` instead of `process.stdout`.
+    Closes task #400 (banner contaminated `telepty list --json | jq`
+    stdin → `Invalid numeric literal`). A new lint-style regression
+    test (`test/banner-stderr-jq-safety.test.js`) statically scans
+    `cli.js` and fails CI if any "⚙️/⚠️ Daemon…" banner regresses
+    back to `process.stdout.write`.
+  - New pure-functional `src/version-handshake.js` exposes
+    `decideVersionAction({ daemonVersion, cliVersion })` returning a
+    stable action enum (`START` / `RESTART` / `NOOP`) plus reason.
+    Six-cell decision matrix: daemon unreachable, CLI-version missing,
+    versions equal, daemon older (newer-wins → restart), daemon newer
+    (preserve newer daemon → noop), non-semver (string compare).
+    Wired into `cli.js` `ensureDaemonRunning` so the previously-inline
+    `meta.version !== pkg.version` check now delegates to the module.
+  - New port-owner fallback in `daemon-control.js`:
+    `findPortOwnerPid(port)` uses `lsof -nP -iTCP:<port> -sTCP:LISTEN -t`
+    on POSIX and `Get-NetTCPConnection -State Listen -LocalPort <port>`
+    on Windows. `cleanupDaemonProcesses` now treats the listener as a
+    third kill candidate (`source: 'port-owner'`) — but only after
+    confirming the PID is actually a telepty daemon via
+    `pidMatchesTeleptyCmdline`. Unconfirmed port-owners are never
+    killed (zero-arbitrary-kill safety). `probeTeleptyOnPort` (HTTP
+    `/api/health`) is exported for future async-aware callers.
+  - SIGTERM → SIGKILL grace period bumped from 1500 ms to 5000 ms
+    (POSIX). Configurable via `TELEPTY_DAEMON_KILL_GRACE_MS` env.
+  - New `src/win-kill-process.js` (parallel to existing
+    `src/win-resolve-executable.js`) provides `buildTaskkillArgs(pid)`
+    and `killWindowsProcess(pid, opts)`. Unit-testable taskkill args
+    generator with injectable `execFileSync`. `daemon-control.js`
+    Windows branch now delegates to this module.
+  - `cleanupDaemonProcesses(opts)` accepts injectors
+    (`readDaemonState`, `listDaemonProcesses`, `findPortOwnerPid`,
+    `pidMatchesTeleptyCmdline`, `stopDaemonProcess`, `includePortOwner`,
+    `port`) for unit-testable source attribution.
+  - **Tests**: 343 / 343 pass (301 baseline preserved + 42 new across
+    four files: `test/version-handshake.test.js` (16),
+    `test/win-kill-process.test.js` (10),
+    `test/daemon-control-port-owner.test.js` (10),
+    `test/banner-stderr-jq-safety.test.js` (6)).
+
+### Notes
+
+- No new npm dependencies (Constitution §17 무의존).
+- No drive-by refactors (Rule 29 surgical); changes limited to
+  `cli.js`, `daemon-control.js`, `src/version-handshake.js` (NEW),
+  `src/win-kill-process.js` (NEW), and four new test files.
+- **Snyk SAST scan on changed files** — `daemon-control.js` +
+  `src/version-handshake.js` + `src/win-kill-process.js` +
+  `test/version-handshake.test.js` +
+  `test/win-kill-process.test.js` +
+  `test/daemon-control-port-owner.test.js` +
+  `test/banner-stderr-jq-safety.test.js` = **0 findings**
+  (At-Inception clean). `cli.js` shows the same **5 pre-existing
+  findings** carried from v0.4.2 (2 Medium Command Injection at
+  `execSync` (was L469 → now L471) and `pty.spawn` (was L1096 → now
+  L1100); 3 Low Path Traversal at `fs.readFileSync`/`fs.readdirSync`
+  (was L2308/L2310/L2619 → now L2312/L2314/L2623)) with **identical
+  fingerprints** vs HEAD~1 (5/5 verified by direct rescan of HEAD~1
+  `cli.js`: fingerprint leading hashes `6eb481d6`, `24799351`,
+  `11a45176`, `11a45176`, `e0fda459` all match). Line numbers
+  downstream of `cli.js:21` shifted +2/+4 due to the new
+  `version-handshake` require + the expanded
+  `restartDaemonGraceful` banner/comment paths; logical
+  source→sink unchanged, no new sink call sites added. Out of
+  telepty#15 surgical scope. Tracked in
+  **dmsdc-ai/aigentry-telepty#26** (task #408) for follow-up PR.
+
+## [0.4.2] - 2026-05-17
+
+### Fixed
+
+- **#28** — SSH-peer routing for `telepty inject` / `list` / `enter`
+  cross-machine: file-backed `peers.json` fallback resolves the prior
+  `fetch failed` against SSH peers in fresh CLI subprocesses. Previously
+  `cross-machine.js` consulted only the in-memory `activePeers` Map, which
+  is process-local and empty for every CLI subprocess spawned after
+  `telepty connect`. New: `listSshPeers` + `getSshPeerHandle` helpers
+  (`cross-machine.js`) make SSH-peer discovery/inject symmetric with the
+  existing HTTP-peer path; `pickSessionTarget` (`session-routing.js`)
+  matches `<id>@<peerName>` against the peer alias; `resolveSessionTarget`
+  (`cli.js`) enriches synthetic targets with `peerName` when the host
+  matches a known SSH peer. 7 new unit tests
+  (`test/cross-machine-ssh-routing.test.js`) + 1 new peer-alias test
+  (`test/session-routing.test.js`). Scope: `inject` / `list` / `enter`;
+  `attach` / `read-screen` / `rename` / `destroy` / `state` /
+  `session info` share the same gap but are deferred to v0.4.3+.
+
+### Notes
+
+- **Snyk SAST scan on changed files** — `cross-machine.js` +
+  `session-routing.js` + `test/cross-machine-ssh-routing.test.js` +
+  `test/session-routing.test.js` = **0 findings** (At-Inception clean).
+  `cli.js` shows **5 pre-existing findings** (2 Medium Command Injection
+  at `execSync` L469 + `pty.spawn` L1096, 3 Low Path Traversal at
+  L2308/L2310/L2619) with **identical fingerprints** vs HEAD~1 (5/5
+  verified). Line numbers for sinks below L543 shifted +21 from the
+  `resolveSessionTarget` enrichment block (cli.js L543–L566) — logical
+  source→sink unchanged; no new sink call sites added. Out of #28
+  surgical scope. Tracked in **dmsdc-ai/aigentry-telepty#26** for
+  follow-up PR.
+
 ## [0.4.1] - 2026-05-17
 
 ### Fixed

package/cli.js

@@ -18,6 +18,7 @@ const { formatHostLabel, groupSessionsByHost, pickSessionTarget } = require('./s
 const { buildSharedContextPrompt, createSharedContextDescriptor, ensureSharedContextFile } = require('./shared-context');
 const { runInteractiveSkillInstaller } = require('./skill-installer');
 const { resolveWindowsExecutable } = require('./src/win-resolve-executable');
+const { decideVersionAction } = require('./src/version-handshake');
 const crossMachine = require('./cross-machine');
 const { parseHostSpec, buildDaemonUrl, buildDaemonWsUrl } = require('./host-spec');
 const { FileMailbox } = require('./src/mailbox/index');
@@ -426,7 +427,8 @@ async function restartDaemonGraceful(options = {}) {
     // Retry with backoff
     if (attempt < maxAttempts) {
       const backoff = 1000 * attempt;
-      process.stdout.write(`\x1b[33m⚠️ Daemon restart attempt ${attempt}/${maxAttempts} failed. Retrying in ${backoff / 1000}s...\x1b[0m\n`);
+      // stderr (not stdout): banner must not contaminate `telepty list --json` (task #400, telepty#15)
+      process.stderr.write(`\x1b[33m⚠️ Daemon restart attempt ${attempt}/${maxAttempts} failed. Retrying in ${backoff / 1000}s...\x1b[0m\n`);
       await new Promise(r => setTimeout(r, backoff));
     }
   }
@@ -542,7 +544,28 @@ function isRemoteSession(session) {
 
 async function resolveSessionTarget(sessionRef, options = {}) {
   const sessions = options.sessions || await discoverSessions({ silent: true });
-  return pickSessionTarget(sessionRef, sessions, REMOTE_HOST);
+  const target = pickSessionTarget(sessionRef, sessions, REMOTE_HOST);
+  // When <id>@<peerName> uses an SSH peer alias (e.g. `winserver`) and the
+  // session is not in `sessions` (discovery missed it, ControlMaster expired,
+  // or remote has no such session), pickSessionTarget returns a synthetic
+  // target with no peerName/remote flag. Detect SSH peer alias here so the
+  // caller routes through cross-machine.remoteInject (SSH path) rather than
+  // falling into the HTTP fetch path with `http://winserver:3848/...`. #411
+  if (
+    target &&
+    !target.peerName &&
+    target.host &&
+    target.host !== '127.0.0.1' &&
+    !target.host.includes(':') &&
+    !target.host.includes('@')
+  ) {
+    const sshPeer = crossMachine.getSshPeerHandle(target.host);
+    if (sshPeer) {
+      target.peerName = target.host;
+      target.remote = true;
+    }
+  }
+  return target;
 }
 
 async function ensureDaemonRunning(options = {}) {
@@ -559,24 +582,26 @@ async function ensureDaemonRunning(options = {}) {
     });
 
     if (sessionsRes.ok && hasCapabilities) {
-      // Version mismatch: running daemon is older than installed CLI
-      if (meta && meta.version !== pkg.version) {
-        process.stdout.write(`\x1b[33m⚙️ Daemon version mismatch (running v${meta.version}, installed v${pkg.version}). Restarting...\x1b[0m\n`);
+      // Delegate decision to pure-functional handshake so the policy is unit-testable
+      // and consistent across CLI invocations.
+      const decision = decideVersionAction({ daemonVersion: meta && meta.version, cliVersion: pkg.version });
+      if (decision.action === 'restart') {
+        // stderr (not stdout): banner must not contaminate `telepty list --json` (task #400, telepty#15)
+        process.stderr.write(`\x1b[33m⚙️ Daemon version mismatch (running v${meta.version}, installed v${pkg.version}). Restarting...\x1b[0m\n`);
         await restartDaemonGraceful({ requiredCapabilities });
         return;
-      } else {
-        return;
       }
+      return;
     } else if (sessionsRes.ok && !meta) {
-      process.stdout.write('\x1b[33m⚙️ Found an older local telepty daemon. Restarting it...\x1b[0m\n');
+      process.stderr.write('\x1b[33m⚙️ Found an older local telepty daemon. Restarting it...\x1b[0m\n');
     } else if (sessionsRes.ok && meta) {
-      process.stdout.write('\x1b[33m⚙️ Found a local telepty daemon without the required features. Restarting it...\x1b[0m\n');
+      process.stderr.write('\x1b[33m⚙️ Found a local telepty daemon without the required features. Restarting it...\x1b[0m\n');
     }
   } catch (e) {
     // Continue to auto-start below.
   }
 
-  process.stdout.write('\x1b[33m⚙️ Auto-starting local telepty daemon...\x1b[0m\n');
+  process.stderr.write('\x1b[33m⚙️ Auto-starting local telepty daemon...\x1b[0m\n');
   await restartDaemonGraceful({ requiredCapabilities });
 }
 

package/cross-machine.js

@@ -37,6 +37,37 @@ function savePeers(data) {
 // In-memory active peers
 const activePeers = new Map(); // name -> { target, controlSocket, connectedAt, machineId }
 
+// File-backed SSH peer enumeration. Required because CLI subprocesses (fresh
+// node procs) start with an empty `activePeers` Map — only the process that
+// called connect() has it populated. peers.json is the cross-process source of
+// truth. controlPath(target) is deterministic, so any process can reuse the
+// ControlMaster socket established by an earlier connect() as long as
+// ControlPersist hasn't expired. See #411.
+function listSshPeers() {
+  const peers = loadPeers().peers || {};
+  return Object.entries(peers)
+    .filter(([, entry]) => getPeerTransport(entry) === 'ssh' && entry && entry.target)
+    .map(([name, entry]) => ({
+      name,
+      target: entry.target,
+      machineId: entry.machineId || name,
+      lastConnected: entry.lastConnected
+    }));
+}
+
+function getSshPeerHandle(name) {
+  if (activePeers.has(name)) return activePeers.get(name);
+  const peers = loadPeers().peers || {};
+  const entry = peers[name];
+  if (!entry || getPeerTransport(entry) !== 'ssh' || !entry.target) return null;
+  return {
+    target: entry.target,
+    controlSocket: controlPath(entry.target),
+    name,
+    machineId: entry.machineId || name
+  };
+}
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
@@ -175,14 +206,11 @@ function disconnectAll() {
  * @returns {Array} sessions with host info
  */
 function listRemoteSessions(name) {
-  const peer = activePeers.get(name);
+  const peer = getSshPeerHandle(name);
   if (!peer) return [];
 
   try {
-    const output = execSync(
-      `ssh -o ControlPath=${peer.controlSocket} ${peer.target} "telepty list --json"`,
-      { timeout: 10000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
-    );
+    const output = runRemoteCommand(peer, 'telepty list --json', { timeout: 10000 });
     const sessions = JSON.parse(output);
     return sessions.map(s => ({ ...s, host: peer.target, peerName: name, remote: true }));
   } catch {
@@ -191,13 +219,21 @@ function listRemoteSessions(name) {
 }
 
 /**
- * Discover sessions across all connected peers.
+ * Discover sessions across all connected peers, including SSH peers that are
+ * persisted in peers.json but not in this process's activePeers Map. Fresh
+ * CLI subprocesses depend on the file-backed path — #411.
  * @returns {Array} all remote sessions
  */
 function discoverAllRemoteSessions() {
   const allSessions = [];
+  const seen = new Set();
   for (const [name] of activePeers) {
     allSessions.push(...listRemoteSessions(name));
+    seen.add(name);
+  }
+  for (const peer of listSshPeers()) {
+    if (seen.has(peer.name)) continue;
+    allSessions.push(...listRemoteSessions(peer.name));
   }
   return allSessions;
 }
@@ -206,7 +242,7 @@ function discoverAllRemoteSessions() {
  * Inject text into a remote session via SSH.
  */
 function remoteInject(name, sessionId, prompt, options = {}) {
-  const peer = activePeers.get(name);
+  const peer = getSshPeerHandle(name);
   if (!peer) return { success: false, error: `Not connected to ${name}` };
 
   try {
@@ -227,7 +263,7 @@ function remoteInject(name, sessionId, prompt, options = {}) {
 }
 
 function remoteEnsureSharedContext(name, descriptor) {
-  const peer = activePeers.get(name);
+  const peer = getSshPeerHandle(name);
   if (!peer) return { success: false, error: `Not connected to ${name}` };
 
   try {
@@ -454,6 +490,9 @@ module.exports = {
   listHttpPeers,
   listHttpRemoteSessions,
   discoverHttpRemoteSessions,
+  // File-backed SSH peer enumeration (cross-process — #411)
+  listSshPeers,
+  getSshPeerHandle,
   getPeerTransport,
   PEERS_PATH
 };

package/daemon-control.js

@@ -3,10 +3,19 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const http = require('http');
 const { execFileSync, execSync } = require('child_process');
+const { killWindowsProcess } = require('./src/win-kill-process');
 
 const TELEPTY_DIR = path.join(os.homedir(), '.telepty');
 const DAEMON_STATE_FILE = path.join(TELEPTY_DIR, 'daemon-state.json');
+const DEFAULT_KILL_GRACE_MS = 5000;
+
+function killGraceMs() {
+  const raw = Number(process.env.TELEPTY_DAEMON_KILL_GRACE_MS);
+  if (Number.isFinite(raw) && raw >= 0) return raw;
+  return DEFAULT_KILL_GRACE_MS;
+}
 
 function ensureTeleptyDir() {
   fs.mkdirSync(TELEPTY_DIR, { recursive: true, mode: 0o700 });
@@ -159,12 +168,12 @@ function stopDaemonProcess(pid) {
 
   try {
     if (process.platform === 'win32') {
-      execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: ['ignore', 'ignore', 'ignore'] });
-      return true;
+      // Windows: delegate to dedicated module so taskkill args are unit-testable.
+      return killWindowsProcess(pid);
     }
 
     process.kill(pid, 'SIGTERM');
-    const deadline = Date.now() + 1500;
+    const deadline = Date.now() + killGraceMs();
     while (Date.now() < deadline) {
       if (!isProcessRunning(pid)) {
         return true;
@@ -179,25 +188,134 @@ function stopDaemonProcess(pid) {
   }
 }
 
-function cleanupDaemonProcesses() {
+// Port-owner discovery for telepty#15 port-owner fallback.
+// Returns the LISTEN-state pid bound to `port` on the local machine, or null
+// if no listener can be identified (or detection failed).
+function findPortOwnerPid(port, opts) {
+  if (!Number.isInteger(port) || port <= 0) return null;
+  const o = opts || {};
+  const platform = o.platform || process.platform;
+  const exec = o.execSync || execSync;
+
+  try {
+    if (platform === 'win32') {
+      // PowerShell: Get-NetTCPConnection guarantees LISTEN-state filter.
+      const script =
+        `Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue ` +
+        `| Select-Object -First 1 -ExpandProperty OwningProcess`;
+      const output = String(exec(`powershell.exe -NoProfile -Command "${script}"`, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      })).trim();
+      const pid = Number(output);
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+
+    // POSIX: lsof -t prints only PIDs; -sTCP:LISTEN narrows to listeners.
+    const output = String(exec(`lsof -nP -iTCP:${port} -sTCP:LISTEN -t`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    })).trim();
+    if (!output) return null;
+    const pid = Number(output.split(/\s+/)[0]);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+// Confirm via HTTP probe that the listener on `port` is actually a telepty
+// daemon (token-less /api/health endpoint is enough — daemon.js:2891 path).
+function probeTeleptyOnPort(port, opts) {
+  if (!Number.isInteger(port) || port <= 0) return Promise.resolve(false);
+  const o = opts || {};
+  const timeoutMs = Number.isFinite(o.timeoutMs) ? o.timeoutMs : 1500;
+  const httpGet = o.httpGet || http.get;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    let req;
+    try {
+      req = httpGet({ hostname: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs }, (res) => {
+        let body = '';
+        res.on('data', (chunk) => { body += chunk; });
+        res.on('end', () => {
+          try {
+            const data = JSON.parse(body);
+            finish(Boolean(data && data.status === 'ok'));
+          } catch {
+            finish(false);
+          }
+        });
+      });
+    } catch {
+      finish(false);
+      return;
+    }
+
+    req.on('error', () => finish(false));
+    req.on('timeout', () => {
+      try { req.destroy(); } catch {}
+      finish(false);
+    });
+  });
+}
+
+// Confirm via local process scan that `pid`'s command line looks like a
+// telepty daemon (fallback when HTTP probe fails — daemon may be stuck).
+function pidMatchesTeleptyCmdline(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    const processes = process.platform === 'win32' ? listWindowsProcesses() : listUnixProcesses();
+    const match = processes.find((item) => item.pid === pid);
+    return Boolean(match && isLikelyTeleptyDaemon(match.commandLine));
+  } catch {
+    return false;
+  }
+}
+
+function cleanupDaemonProcesses(opts) {
+  const o = opts || {};
   const targets = new Map();
-  const state = readDaemonState();
+  const state = (o.readDaemonState || readDaemonState)();
 
   if (state && Number.isInteger(state.pid) && state.pid > 0 && state.pid !== process.pid) {
     targets.set(state.pid, { pid: state.pid, source: 'state-file' });
   }
 
-  for (const item of listDaemonProcesses()) {
+  for (const item of (o.listDaemonProcesses || listDaemonProcesses)()) {
     if (!targets.has(item.pid)) {
       targets.set(item.pid, { pid: item.pid, source: 'process-scan', commandLine: item.commandLine });
     }
   }
 
+  // 3rd source: port-owner fallback (telepty#15).
+  // Only consider it a kill candidate after a confirmation step so we never
+  // SIGTERM an arbitrary process that happens to own the port.
+  // Confirmation order: HTTP /api/health probe → ps cmdline match.
+  // Sync-friendly: HTTP probe is opt-in (port-owner kept disabled in tests).
+  if (o.includePortOwner !== false) {
+    const portOwnerPid = (o.findPortOwnerPid || findPortOwnerPid)(o.port || 3848);
+    if (portOwnerPid && portOwnerPid !== process.pid && !targets.has(portOwnerPid)) {
+      const confirmCmdline = (o.pidMatchesTeleptyCmdline || pidMatchesTeleptyCmdline);
+      if (confirmCmdline(portOwnerPid)) {
+        targets.set(portOwnerPid, { pid: portOwnerPid, source: 'port-owner' });
+      }
+    }
+  }
+
   const stopped = [];
   const failed = [];
 
   for (const item of targets.values()) {
-    if (stopDaemonProcess(item.pid)) {
+    const killer = o.stopDaemonProcess || stopDaemonProcess;
+    if (killer(item.pid)) {
       stopped.push(item);
     } else {
       failed.push(item);
@@ -217,7 +335,10 @@ module.exports = {
   claimDaemonState,
   cleanupDaemonProcesses,
   clearDaemonState,
+  findPortOwnerPid,
   isProcessRunning,
   listDaemonProcesses,
+  pidMatchesTeleptyCmdline,
+  probeTeleptyOnPort,
   readDaemonState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -33,9 +33,9 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js test/win-resolve-executable.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js test/win-resolve-executable.test.js",
-    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/init.test.js test/win-resolve-executable.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js",
+    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
   "keywords": [

package/session-routing.js

@@ -38,7 +38,12 @@ function pickSessionTarget(sessionRef, sessions, defaultHost = '127.0.0.1') {
   }
 
   if (parsed.host) {
-    const exactMatch = sessions.find((session) => session.id === parsed.id && session.host === parsed.host);
+    // Match by host or by peerName alias (e.g. `sid@winserver` where
+    // winserver is the SSH peer name and session.host is `user@FQDN`). #411
+    const exactMatch = sessions.find((session) =>
+      session.id === parsed.id &&
+      (session.host === parsed.host || session.peerName === parsed.host)
+    );
     return exactMatch || { id: parsed.id, host: parsed.host };
   }
 

package/src/version-handshake.js

@@ -0,0 +1,82 @@
+// src/version-handshake.js — pure-functional daemon/CLI version handshake policy.
+//
+// Fixes telepty#15 (auto-restart on daemon version mismatch) and task #400
+// (mismatch-banner-on-stdout contaminates `telepty list --json | jq`).
+//
+// Decision policy (newer-wins; daemon-side EADDRINUSE health-probe already
+// handles the symmetric case where a newer daemon refuses to clobber). Input
+// is the daemon `/api/meta` response (or null when unreachable) plus the local
+// CLI package version. Output is a stable action enum the caller maps to side
+// effects (restart vs noop vs start). Pure → unit-testable without sockets.
+//
+// Constraints honored:
+//   - Constitution §1 lightweight: ≤80 lines core logic, no deps.
+//   - Constitution §2 cross-platform: pure JS, no OS calls.
+//   - Constitution §17 무의존: no new npm dependencies.
+
+'use strict';
+
+const ACTIONS = Object.freeze({
+  NOOP: 'noop',
+  RESTART: 'restart',
+  START: 'start'
+});
+
+function parseSemver(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareSemver(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] !== right[i]) return left[i] < right[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+function decideVersionAction(input) {
+  const daemonVersion = input && input.daemonVersion;
+  const cliVersion = input && input.cliVersion;
+
+  // No daemon reachable → caller should start one (separate from restart).
+  if (!daemonVersion) {
+    return { action: ACTIONS.START, reason: 'daemon-unreachable' };
+  }
+  if (!cliVersion) {
+    return { action: ACTIONS.NOOP, reason: 'cli-version-missing' };
+  }
+
+  const cmp = compareSemver(daemonVersion, cliVersion);
+
+  // Non-semver values: fall back to string compare so dev/test tags still flow.
+  if (cmp === null) {
+    if (daemonVersion === cliVersion) {
+      return { action: ACTIONS.NOOP, reason: 'versions-equal-nonsemver' };
+    }
+    return { action: ACTIONS.RESTART, reason: 'version-mismatch-nonsemver' };
+  }
+
+  if (cmp === 0) {
+    return { action: ACTIONS.NOOP, reason: 'versions-equal' };
+  }
+  if (cmp < 0) {
+    // Daemon older than CLI → newer-wins, restart.
+    return { action: ACTIONS.RESTART, reason: 'daemon-older' };
+  }
+  // Daemon newer than CLI → respect newer daemon; CLI talks via HTTP wire
+  // protocol that is forward-compatible. No restart (avoid clobbering newer).
+  return { action: ACTIONS.NOOP, reason: 'daemon-newer' };
+}
+
+module.exports = {
+  ACTIONS,
+  decideVersionAction,
+  // Exported for tests + reuse by daemon-control.js port-owner probe.
+  parseSemver,
+  compareSemver
+};

package/src/win-kill-process.js

@@ -0,0 +1,51 @@
+// src/win-kill-process.js — Windows process-kill helper.
+//
+// Fixes telepty#15 (port-owner fallback when stale daemon holds port 3848).
+// On Windows `process.kill(pid, 'SIGTERM')` is unreliable for daemons spawned
+// in a different console group; `taskkill /T /F` is the supported path.
+//
+// On POSIX this module is a no-op (callers fall back to native SIGTERM →
+// SIGKILL grace inline in `daemon-control.js`).
+//
+// Exports:
+//   buildTaskkillArgs(pid)        → ['/PID', '<pid>', '/T', '/F']
+//   killWindowsProcess(pid, opts) → boolean — true on success
+//
+// Constraints honored:
+//   - Constitution §1 lightweight: ≤80 lines, child_process only.
+//   - Constitution §2 cross-platform: POSIX → returns false fast.
+//   - Constitution §17 무의존: no new dependencies.
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+function buildTaskkillArgs(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error('telepty: buildTaskkillArgs requires a positive integer pid');
+  }
+  return ['/PID', String(pid), '/T', '/F'];
+}
+
+function killWindowsProcess(pid, opts) {
+  const o = opts || {};
+  const platform = o.platform || process.platform;
+  if (platform !== 'win32') return false;
+
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+
+  const exec = o.execFileSync || execFileSync;
+  try {
+    exec('taskkill', buildTaskkillArgs(pid), { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  buildTaskkillArgs,
+  killWindowsProcess
+};