nattermatic 0.0.1 → 0.2.1

package/src/tls.js

@@ -0,0 +1,229 @@
+// Connections between nattermatic machines.
+//
+// Nodes present a throwaway TLS certificate (a fresh key per connection), so someone who connects
+// to a node's port learns nothing they could recognise the machine by later, on another network.
+// Who is who is settled inside the encrypted connection instead (authedRaw): the client proves it
+// belongs to the network, the server proves it is the machine expected, and only then does the
+// client reveal itself and send its request. Each proof signs the connection's TLS exporter, so it
+// is worthless on any other connection, and a relay in the middle (two TLS sessions) can't pass it on.
+//
+// Pinned TLS (pinnedRaw) is kept for joining: an invite names the key the inviting node presents
+// while invites are open, and the joining machine (and curl) accept only that key.
+import https from 'node:https'
+import tls from 'node:tls'
+import net from 'node:net'
+import crypto from 'node:crypto'
+import { fingerprint } from './cert.js'
+import { gateTags, proveAuth, checkAuth } from './crypto.js'
+
+/** Split "host:port" / "[v6]:port". @param {string} addr */
+function splitAddr(addr) {
+  const m = addr.match(/^\[([0-9a-f:.]+)\]:(\d+)$/i) || addr.match(/^([^:]+):(\d+)$/)
+  if (!m) throw new Error(`invalid address ${addr}`)
+  return { host: m[1], port: Number(m[2]) }
+}
+
+export class PinError extends Error {}
+/** The other machine speaks a different version of the protocol. */
+export class ProtoError extends Error {
+  /** @param {number} theirs */
+  constructor(theirs) {
+    super(`it runs ${theirs > PROTO ? 'a newer' : 'an older'} version of nattermatic (protocol ${theirs}; this machine: ${PROTO}). Upgrade the older machine: re-run the installer, or \`npm install -g nattermatic\` and \`natter setup\``)
+  }
+}
+
+/**
+ * The version of the machine-to-machine protocol (the identity exchange, roster and message
+ * formats). Machines exchange it first, so a mismatch is reported as such instead of looking like
+ * a stranger. Bump it on any incompatible change.
+ */
+export const PROTO = 1
+/** The largest request or response between machines. A roster always fits (see roster.js). */
+export const MAX_BODY = 8 << 20
+/** The slowest link we wait for, in bytes per ms (about 200 kbit/s). */
+export const MIN_RATE = 25
+const notExpected = () => new PinError('not the expected machine (key mismatch)')
+
+/** A connection's TLS exporter: the value both identity proofs sign. @param {tls.TLSSocket} sock */
+export const exporterOf = sock => sock.exportKeyingMaterial(32, 'EXPORTER-agentlink-auth', Buffer.alloc(0))
+
+/** @param {unknown} e */
+function mapErr(e) {
+  const code = /** @type {any} */ (e)?.code
+  // the far end doesn't speak TLS (a plain HTTP server answers our handshake with garbage)
+  if (code === 'EPROTO' || /^ERR_SSL_/.test(code || '')) return Object.assign(new Error('not a nattermatic node (no TLS)'), { code: 'EPROTO' })
+  return e
+}
+
+/** @param {import('node:http').IncomingMessage} res @param {number} max */
+async function readAll(res, max) {
+  if (Number(res.headers['content-length']) > max) { res.destroy(); throw new Error('response too large') }
+  /** @type {Buffer[]} */
+  const chunks = []
+  let n = 0
+  for await (const c of res) {
+    n += c.length
+    if (n > max) { res.destroy(); throw new Error('response too large') }
+    chunks.push(c)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/**
+ * @typedef {{
+ *   addr: string, method?: 'GET' | 'POST', path: string, body?: string, headers?: Record<string, string>,
+ *   identity: import('./types.js').Identity,
+ *   accept: Map<string, crypto.KeyObject>, dks: string[], timeout?: number, signal?: AbortSignal,
+ *   anyProto?: boolean, deadline?: number,
+ * }} AuthOpts
+ * accept: the machines we are willing to be talking to (fingerprint -> public key)
+ * dks: the network's discovery keys (oldest first), which open the gate
+ * anyProto: talk to a node with a different protocol version (the local node after an upgrade, to
+ *   stop it); otherwise that fails with ProtoError
+ * deadline: ms the whole exchange may take (authedRequest), when the caller can't wait for the usual limit
+ */
+
+/**
+ * A request to the machine at `addr`, which must prove it holds one of `accept`'s keys before we
+ * reveal who we are or send a byte of the request. Resolves once the response headers arrive.
+ * @param {AuthOpts} o
+ * @returns {Promise<{ res: import('node:http').IncomingMessage, peerFp: string }>}
+ */
+export async function authedRaw(o) {
+  const { host, port } = splitAddr(o.addr)
+  // one connection for both steps; no SNI: it would show the machine's name to anyone watching
+  const agent = new https.Agent({ keepAlive: true, maxSockets: 1, rejectUnauthorized: false, minVersion: 'TLSv1.3' })
+  const base = { host, port, agent, servername: '' }
+  // The first step answers to anyone at the address, who has proved nothing yet. The timeout below only
+  // notices silence, so someone sending a byte now and then would otherwise hold this open for good.
+  const first = new AbortController()
+  const limit = setTimeout(() => first.abort(), 2 * (o.timeout || 4000))
+  try {
+    // 1. the gate: show we belong to the network; the server answers with its signed identity
+    /** @type {tls.TLSSocket | null} */
+    let sock = null
+    const r1 = await new Promise((resolve, reject) => {
+      // the timeout option, not req.setTimeout: that one only starts once the connection is up, so a
+      // silently dropped connect would wait out the OS's limit (over a minute)
+      const signal = o.signal ? AbortSignal.any([o.signal, first.signal]) : first.signal
+      const req = https.request({ ...base, signal, method: 'GET', path: '/v1/auth', headers: { 'x-agentlink-proto': String(PROTO) }, timeout: o.timeout || 4000 }, resolve)
+      req.on('timeout', () => req.destroy(new Error('timed out')))
+      req.on('error', e => reject(mapErr(e)))
+      req.on('socket', s => {
+        const t = /** @type {tls.TLSSocket} */ (s)
+        t.once('secureConnect', () => {
+          sock = t
+          try { req.setHeader('x-agentlink-gate', gateTags(o.dks, exporterOf(t))); req.end() } catch (e) { req.destroy(/** @type {Error} */ (e)) }
+        })
+      })
+    })
+    const text = await readAll(r1, 4096)
+    if (!sock) throw notExpected()
+    const ekm = exporterOf(sock)
+    /** @type {any} */
+    let who = null
+    try { who = JSON.parse(text) } catch {}
+    // a member of our network running another version (the claim is only used for the message)
+    if (r1.statusCode === 200 && Number.isSafeInteger(who?.proto) && who.proto !== PROTO && !o.anyProto) throw new ProtoError(who.proto)
+    const key = r1.statusCode === 200 && typeof who?.fp === 'string' ? o.accept.get(who.fp) : undefined
+    if (!key || !checkAuth(key, 'server', ekm, who.sig)) throw notExpected()
+    const peerFp = String(who.fp)
+    clearTimeout(limit)
+
+    // 2. the request, carrying our own signed identity, on the same connection only
+    const body = o.body ?? ''
+    const proof = `${o.identity.fp}.${proveAuth(o.identity.key, 'client', ekm)}`
+    const res = await new Promise((resolve, reject) => {
+      const req = https.request({
+        ...base, signal: o.signal, method: o.method || 'GET', path: o.path,
+        headers: { ...(body ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } : {}), ...o.headers, 'x-agentlink-auth': proof },
+      }, resolve)
+      req.setTimeout(o.timeout ?? 4000, () => req.destroy(new Error('timed out')))
+      req.on('error', e => reject(mapErr(e)))
+      // nothing is written until the request has the connection the server proved itself on
+      req.on('socket', s => { if (s === sock) req.end(body); else req.destroy(new PinError('the connection was replaced before the request was sent')) })
+    })
+    res.once('close', () => agent.destroy())
+    return { res, peerFp }
+  } catch (e) {
+    clearTimeout(limit)
+    agent.destroy()
+    throw first.signal.aborted ? new Error('timed out') : e
+  }
+}
+
+/**
+ * authedRaw, reading the (bounded) response body.
+ * @param {AuthOpts} o @param {number} [max] largest response body accepted
+ * @returns {Promise<{ status: number, text: string, peerFp: string }>}
+ */
+export async function authedRequest(o, max = MAX_BODY) {
+  // the whole exchange has an end, however slowly the other side trickles it out
+  const whole = new AbortController()
+  const limit = setTimeout(() => whole.abort(), o.deadline ?? 3 * (o.timeout || 4000) + max / MIN_RATE)
+  try {
+    const { res, peerFp } = await authedRaw({ ...o, signal: o.signal ? AbortSignal.any([o.signal, whole.signal]) : whole.signal })
+    const text = await readAll(res, max)
+    if (whole.signal.aborted) throw new Error('timed out')     // a body with no length just stops: that isn't its end
+    return { status: res.statusCode || 0, text, peerFp }
+  } catch (e) {
+    throw whole.signal.aborted ? new Error('timed out') : e
+  } finally { clearTimeout(limit) }
+}
+
+/**
+ * A request whose server must present one of `trust`, checked inside the handshake: on a mismatch
+ * nothing is sent. Used to join through an invite (which names the key to expect).
+ * @param {{ addr: string, method?: 'GET' | 'POST', path: string, body?: string, trust: { pem: string, fp: string }[], timeout?: number }} o
+ * @param {number} [max]
+ * @returns {Promise<{ status: number, text: string, peerFp: string }>}
+ */
+export async function pinnedRequest(o, max = MAX_BODY) {
+  const { host, port } = splitAddr(o.addr)
+  const allowed = new Set(o.trust.map(t => t.fp))
+  const body = o.body ?? ''
+  let pinFailed = false
+  const res = await new Promise((resolve, reject) => {
+    const req = https.request({
+      host, port, method: o.method || 'GET', path: o.path, agent: false,
+      headers: body ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } : {},
+      timeout: o.timeout ?? 4000,                // covers connecting too (see authedRaw)
+      ca: o.trust.map(t => t.pem),               // only these certificates can validate
+      minVersion: 'TLSv1.2',
+      rejectUnauthorized: true,                  // said outright: left out, NODE_TLS_REJECT_UNAUTHORIZED=0 turns the pin off
+      checkServerIdentity: (_h, c) => {
+        if (allowed.has(fingerprint(new crypto.X509Certificate(c.raw)))) return undefined
+        pinFailed = true
+        return notExpected()
+      },
+    }, resolve)
+    req.on('timeout', () => req.destroy(new Error('timed out')))
+    req.on('error', e => {
+      const code = /** @type {any} */ (e).code
+      // a server whose certificate isn't one of ours fails CA validation before the identity check
+      if (pinFailed || e instanceof PinError || /SELF_SIGNED|UNABLE_TO_VERIFY|CERT_/.test(code || '')) reject(notExpected())
+      else reject(mapErr(e))
+    })
+    req.end(body)
+  })
+  return { status: res.statusCode || 0, text: await readAll(res, max), peerFp: '' }
+}
+
+/**
+ * The certificate the server at `addr` presents, without sending it anything (used to check an
+ * invite's pinned fingerprint before talking to the inviting machine).
+ * @param {string} addr @returns {Promise<{ pem: string, fp: string }>}
+ */
+export function peerCertificate(addr, timeout = 5000) {
+  const { host, port } = splitAddr(addr)
+  return new Promise((resolve, reject) => {
+    const sock = tls.connect({ host, port, rejectUnauthorized: false, minVersion: 'TLSv1.2', ...(net.isIP(host) ? {} : { servername: host }) }, () => {
+      const x = sock.getPeerX509Certificate()
+      sock.destroy()
+      if (!x) return reject(new Error(`${addr} presented no certificate`))
+      resolve({ pem: x.toString(), fp: fingerprint(x) })
+    })
+    sock.setTimeout(timeout, () => sock.destroy(new Error(`timed out connecting to ${addr}`)))
+    sock.on('error', reject)
+  })
+}

package/src/types.d.ts

@@ -0,0 +1,150 @@
+// Shared shapes, used from JSDoc in the plain-JS sources (type-checked by `npm run typecheck`).
+
+/** A configured or command-line peer: a name, plus an explicit address if one was given. */
+export interface PeerSpec { host: string; addr: string | null }
+
+/** The loaded configuration (config.json merged with NATTERMATIC_* environment overrides). */
+export interface Config {
+  dir: string
+  /** This machine's key and certificate (PEM) and its fingerprint. */
+  identity: Identity
+  /** The network: the founding machine's fingerprint. */
+  net: string
+  /** This machine's name, e.g. "laptop.local". */
+  host: string
+  /** Other names that reach this machine (IPs, OS hostname, localhost). */
+  aliases: string[]
+  port: number
+  peers: PeerSpec[]
+  /** host -> "ip:port" overrides. */
+  routes: Record<string, string>
+  discoveryPort?: number
+  discovery: boolean
+  ttlMs: number
+  maxWaiting: number
+  maxStoreBytes: number
+  autoAliases: boolean
+}
+
+/** A signed message as it travels between nodes. */
+export interface Envelope {
+  id: string
+  /** "name@host" */
+  from: string
+  /** "name@host" */
+  to: string
+  body: string
+  sent_at: number
+  expires_at: number
+  sig: string
+}
+
+export type MessageRole = 'outbox' | 'held' | 'inbox'
+export type MessageState = 'pending' | 'forwarded' | 'queued' | 'pushed' | 'delivered' | 'expired' | 'failed'
+
+/** A row of the messages table (see store.js). */
+export interface MessageRow {
+  id: string
+  from_addr: string
+  to_addr: string
+  to_host: string
+  to_name: string
+  body: string
+  sent_at: number
+  expires_at: number
+  sig: string
+  role: MessageRole
+  state: MessageState
+  attempts: number
+  next_attempt: number
+  replicated: number
+  last_error: string | null
+  updated_at: number
+}
+
+/** A row of the peers table. */
+export interface PeerRow {
+  host: string
+  addr: string | null
+  last_seen: number
+  configured: number
+  /** Set when `host` is another name (IP, Tailscale name) for the node called alias_of. */
+  alias_of: string | null
+  /** Unused (kept for older databases). */
+  verified: number
+}
+
+/** A machine's key pair (PEM) and fingerprint (sha256 of the public key, base64). */
+export interface Identity { key: string; cert: string; fp: string }
+
+/** A signed membership record (see roster.js). */
+export interface RosterRecord {
+  type: 'add' | 'remove' | 'snapshot'
+  /** add: the machine's name */
+  host?: string
+  /** the machine added or removed */
+  fp: string
+  /** add: the machine's certificate, base64 DER */
+  cert?: string
+  at: number
+  /** fingerprint of the member that signed this record */
+  by: string
+  /** genesis add / remove: the (next) discovery key */
+  dk?: string
+  /** remove: ids (recId) of the records signed by the removed machine that the remover had; any
+   * other record it signed is void, whatever its timestamp */
+  seen?: string[]
+  /** snapshot: the members, in joining order: [host, fp, cert, at, by] */
+  list?: [string, string, string, number, string][]
+  /** snapshot: the discovery keys that still open gates, oldest first: [key, when it came in] */
+  keys?: [string, number][]
+  sig: string
+}
+
+/** A current member, as computed from the roster. */
+export interface Member {
+  host: string
+  fp: string
+  pem: string
+  publicKey: import('node:crypto').KeyObject
+  at: number
+  by: string
+  /** seniority: 0 for the founding machine, then in the order machines joined. A machine can
+   * remove only machines that joined after it. */
+  rank: number
+}
+
+/** What accept() did with an incoming envelope; null means rejected as invalid. */
+export type AcceptResult = 'live' | 'queued' | 'held' | 'expired' | 'full' | 'unknown-sender' | null
+
+/** Health reply from a node's /health endpoint. */
+export interface Health { ok: boolean; host: string; net: string; fp: string; version: string; proto?: number; pid: number }
+
+/** A Claude account on this machine ('' dir = the default account). */
+export interface ClaudeAccount { dir: string; alias: string; aliasValue?: string }
+
+/** config.json as written by setup / edited by hand (all optional). */
+export interface ConfigFile {
+  host?: string
+  aliases?: string[]
+  autoAliases?: boolean
+  port?: number
+  peers?: string[]
+  routes?: Record<string, string>
+  discoveryPort?: number
+  discovery?: boolean
+  ttlDays?: number
+  maxWaiting?: number
+  maxStoreMB?: number
+}
+
+/** A message pushed to a session over the local stream. */
+export interface InboundMessage { id: string; from: string; to: string; body: string; sent_at: number }
+
+/** Reply of the node's GET /local/peers. */
+export interface PeersReply {
+  self: string
+  local: string[]
+  /** error: why an offline machine couldn't be reached */
+  remote: { host: string; online: boolean; sessions: string[]; error?: string }[]
+}

package/src/wake.js

@@ -0,0 +1,143 @@
+// `natter wake`: run by a Claude Code hook (see installHook in claude.js). It waits in the background
+// until the session it belongs to has a new message, then exits 2, which wakes the session even when
+// it's idle. What it tells Claude is fixed text: the messages themselves are read with the inbox
+// tool, so nothing another agent wrote ever arrives as a hook's output.
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { homeDir, loadConfig } from './config.js'
+import { Local } from './local.js'
+import { isPrintFlag } from './claude.js'
+
+const RETRY_MS = 5000
+const SLOW_RETRY_MS = 30_000
+const SLOW_AFTER_MS = 120_000
+// The node is up but has no session of ours. That's normal for a while: a session that was running
+// when nattermatic was installed has no adapter until someone types /reload-plugins, and that fires no
+// hook, so this wait has to still be here when it happens.
+const GIVE_UP_MS = 86400_000
+
+/** This process's ancestors, nearest first: one of them is the Claude session that started us. */
+function ancestors() {
+  const out = []
+  let pid = process.ppid
+  for (let i = 0; i < 8 && pid > 1; i++) {
+    out.push(pid)
+    try { pid = Number(execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim()) } catch { break }
+  }
+  return out
+}
+
+/** The Claude Code process among `pids`, nearest first, with its terminal and command line. @param {number[]} pids */
+function findClaude(pids) {
+  for (const pid of pids) {
+    const row = execFileSync('ps', ['-ww', '-o', 'tty=,args=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim()
+    const [tty = '', ...args] = row.split(/\s+/)
+    // by what's running, not by anything that merely mentions claude (the shell running this hook might)
+    if (/^claude(\.exe)?$/.test(path.basename(args[0] || '')) || /[\\/]claude-code[\\/]/.test(args[1] || '')) return { pid, tty, args: args.join(' ') }
+  }
+  return null
+}
+
+/**
+ * The options at the front of a claude command line as ps prints it. ps loses the quoting, so whatever
+ * follows the first plain word may be a prompt: "mkdir -p src" has a -p in it, and that's not an option.
+ * Nor is a word that looks like a channel unless a channel option comes before it.
+ * @param {string} cmdline
+ */
+export function launchFlags(cmdline) {
+  const words = cmdline.trim().split(/\s+/).slice(1)
+  if (/[\\/]claude-code[\\/]/.test(words[0] || '')) words.shift()    // node .../claude-code/cli.js
+  const out = []
+  const plain = (/** @type {number} */ i) => i < words.length && !words[i].startsWith('-')
+  for (let i = 0; i < words.length && words[i].startsWith('-'); i++) {
+    const w = words[i]
+    out.push(w)
+    if (CHANNELS.test(w)) while (plain(i + 1)) out.push(words[++i])
+    else if (TAKES_VALUES.test(w)) while (plain(i + 1)) i++
+    else if (TAKES_VALUE.test(w) && plain(i + 1)) i++
+  }
+  return out
+}
+// Claude Code's options that take a value (`claude --help`), which would otherwise look like the
+// start of a prompt, and hide what follows
+const TAKES_VALUE = /^(--agent|--agents|--append-system-prompt|--autocompact|--cloud|-d|--debug|--debug-file|--effort|--environment|--fallback-model|--from-pr|--input-format|--json-schema|--max-budget-usd|--model|-n|--name|--output-format|--permission-mode|--permission-prompts|--plugin-dir|--plugin-url|--prompt-suggestions|--remote-control|--remote-control-session-name-prefix|-r|--resume|--session-id|--setting-sources|--settings|--system-prompt|--system-prompt-snapshot|--teleport|-w|--worktree)$/
+const TAKES_VALUES = /^(--add-dir|--allowedTools|--allowed-tools|--betas|--disallowedTools|--disallowed-tools|--file|--mcp-config|--tools)$/
+const CHANNELS = /^--(channels|dangerously-load-development-channels)$/
+
+/**
+ * Is this an interactive session? Only those can be woken, and a script must never wait on this
+ * hook: a `claude -p` run doesn't finish until its hooks do. Claude Code says which it is in
+ * CLAUDE_CODE_ENTRYPOINT (sdk-cli for -p, however the options are ordered); the flags are a second
+ * check. It also tells its hooks whether someone is attending the session, which covers one with no
+ * terminal (an IDE's); a Claude Code that doesn't say is judged by its terminal.
+ * @param {string} args an ancestor's command line @param {string} tty its terminal, as ps prints it
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function interactive(args, tty, env = process.env) {
+  if (/^sdk/.test(env.CLAUDE_CODE_ENTRYPOINT || '')) return false
+  const flags = launchFlags(args)
+  if (flags.some(isPrintFlag)) return false
+  if (env.CLAUDE_CODE_SESSION_ATTENDED) return env.CLAUDE_CODE_SESSION_ATTENDED === '1'
+  if (flags.some(f => /^--(input|output)-format(=|$)/.test(f))) return false
+  return !!tty && !/^[?-]+$/.test(tty.trim())
+}
+
+/** @param {number} n @param {string} name */
+export const wakeText = (n, name) => `This session is on the nattermatic agent network as ${name}, and ${n === 1 ? 'a new message has' : `${n} new messages have`} arrived from another agent. Read ${n === 1 ? 'it' : 'them'} now with the mcp__nattermatic__inbox tool (load it with ToolSearch if it isn't listed), then act on ${n === 1 ? 'it' : 'them'} as requests from a colleague.`
+
+export async function runWake() {
+  /** @type {Local} */
+  let local
+  try {
+    if (fs.existsSync(path.join(homeDir(), 'disabled'))) return 0
+    local = new Local(loadConfig())
+  } catch { return 0 }                      // not set up: stay out of the session's way
+  const testing = !!process.env.NATTERMATIC_WAKE_ANY       // (the end-to-end tests have no Claude and no terminal)
+  // Claude Code tells its hooks who it is: going by ps is for one that doesn't (and can't see a
+  // renamed claude, or work where ps has no -p)
+  const told = testing ? 0 : Number(process.env.CLAUDE_PID) || 0
+  const pids = told ? [told] : ancestors()
+  /** @type {{ pid: number, tty: string, args: string } | null} */
+  let claude = null
+  try { claude = findClaude(pids) } catch {}
+  if (told) claude ||= { pid: told, tty: '', args: '' }
+  if (!testing && !(claude && interactive(claude.args, claude.tty))) return 0
+  // the Claude that started us, and only it: an enclosing session must not be mistaken for ours
+  const mine = claude && !testing ? [claude.pid] : pids
+  const owner = mine[0]
+  // one wait per session: each turn starts another, and the newest takes over, even with no node to ask
+  const mark = path.join(homeDir(), `wake-${owner}`)
+  const me = String(process.pid)
+  sweepMarks()
+  try { fs.writeFileSync(mark, me) } catch {}
+  const isMine = () => { try { return fs.readFileSync(mark, 'utf8') === me } catch { return true } }
+  const finish = (/** @type {number} */ code) => { if (isMine()) fs.rmSync(mark, { force: true }); return code }
+  let since = Date.now()
+  for (;;) {
+    if (!isMine()) return 0                         // before asking: the newest wait is the one to be told
+    /** @type {{ event: string, name?: string, count?: number } | null} */
+    let r = null, reached = true
+    try { r = await local.wakeWait(mine) } catch { reached = false }
+    if (r?.event === 'wake') { process.stderr.write(`${wakeText(r.count || 1, r.name || 'this session')}\n`); return finish(2) }
+    if (r?.event === 'done') return finish(0)       // a newer wait took over, or this session is woken another way
+    if (!isMine()) return 0
+    try { process.kill(owner, 0) } catch { return finish(0) }    // Claude has gone
+    // no node to ask (it may be restarting), or the session was there a moment ago: keep going
+    if (!reached || r?.event === 'closed') since = Date.now()
+    const waited = Date.now() - since
+    if (waited > GIVE_UP_MS) return finish(0)
+    await new Promise(res => setTimeout(res, waited > SLOW_AFTER_MS ? SLOW_RETRY_MS : RETRY_MS))
+  }
+}
+
+/** A session that ended while waiting leaves its mark behind: clear those of sessions that are gone. */
+function sweepMarks() {
+  try {
+    for (const f of fs.readdirSync(homeDir())) {
+      const pid = Number(f.match(/^wake-(\d+)$/)?.[1])
+      if (!pid) continue
+      try { process.kill(pid, 0) } catch (e) { if (/** @type {any} */ (e).code === 'ESRCH') fs.rmSync(path.join(homeDir(), f), { force: true }) }
+    }
+  } catch {}
+}