@myelinbridge/cli 0.12.2 → 0.14.0

package/bin/myelin.js

@@ -40,10 +40,27 @@
 // for), even though `check` correctly warned about it via preflight. The API
 // now includes required-but-empty fields in `metadata` too
 // (`required: true`, `value: null`), and `contract` renders them.
+//
+// 0.13.0 — the CLI reaches the network the way a corporate pipeline host
+// actually reaches it. HTTPS_PROXY / HTTP_PROXY / NO_PROXY (either case) are
+// honoured on every call, API and part upload alike; before this, Node's
+// global fetch ignored all three and a partner whose only egress is a proxy
+// could not deliver at all — the failure read as Myelin being down. The
+// transport is now ours (node:http/node:https, still zero dependencies), so
+// there is one path whether or not a proxy is in the picture. Two smaller
+// consequences: a part upload that cannot reach storage now names the host it
+// could not reach (never the presigned URL — its query string is the
+// credential), and `ping` prints the proxy it used. The hosts and ports a
+// partner's firewall must allow are written down for the first time, in the
+// README's "For your IT department" section.
 
 import { readdirSync, statSync, createReadStream, readFileSync } from 'node:fs'
 import { resolve, join, relative, sep, basename } from 'node:path'
 import { createHash } from 'node:crypto'
+import http from 'node:http'
+import https from 'node:https'
+import tls from 'node:tls'
+import zlib from 'node:zlib'
 import process from 'node:process'
 
 const API_URL = (process.env.MYELIN_API_URL ?? 'https://myelinbridge.com/api/v1').replace(/\/$/, '')
@@ -154,13 +171,404 @@ function opt(name) {
   return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : null
 }
 
+// ── Egress: the corporate network this CLI actually runs on ────────────────
+//
+// A CRO's pipeline host usually has no route to the internet of its own. Its
+// only way out is an HTTP CONNECT proxy named by HTTPS_PROXY / HTTP_PROXY,
+// with NO_PROXY listing what must stay inside. Node's global `fetch` ignores
+// all three — Node 22+ honours them only if NODE_USE_ENV_PROXY=1 was set
+// before the process started, Node 20 not at all — so until 0.13.0 every
+// command dialled straight out and died with `fetch failed`. A partner whose
+// only egress is a proxy could not deliver a single byte, and it read as
+// Myelin being down rather than as a variable nobody had honoured.
+//
+// So the CLI speaks the proxy protocol itself, over node:http / node:https,
+// and adds no dependency to do it: this is a binary a customer's IT
+// department installs, and an empty `dependencies` is worth more than the
+// ~200 lines below. It is also the only fix that reaches every Node in
+// `engines` — the undici workaround needs a NODE_OPTIONS preload and a
+// package we would have to ship.
+//
+// One transport for every call, proxied or not. Keeping `fetch` for the
+// direct case would have left the proxy path running only at customer sites,
+// which is the definition of a path that rots.
+//
+// ⚠ Every request carries an explicit agent, always. Node ≥24.5 can install a
+// proxy-aware global agent of its own; if it ever did so under us, a request
+// we had already tunnelled would be tunnelled twice. Our own agent means one
+// behaviour on every Node we support.
+
+const UA = `myelin-cli/${VERSION} (node ${process.versions.node})`
+
+// Lowercase first — curl's precedence, and the spelling most pipelines set.
+// Both are read because both are in the wild: on Windows they are the same
+// variable, on Linux they are not, and which spelling we happened to prefer
+// must never become the partner's problem.
+const envPair = (...names) => {
+  for (const name of names) {
+    const value = process.env[name]
+    if (typeof value === 'string' && value.trim()) return { name, value: value.trim() }
+  }
+  return null
+}
+const httpsProxyEnv = () => envPair('https_proxy', 'HTTPS_PROXY')
+const httpProxyEnv = () => envPair('http_proxy', 'HTTP_PROXY')
+const noProxyEnv = () => envPair('no_proxy', 'NO_PROXY')
+const anyProxyEnv = () => Boolean(httpsProxyEnv() || httpProxyEnv())
+
+const ipv4ToInt = (ip) => {
+  const parts = ip.split('.')
+  if (parts.length !== 4) return null
+  let n = 0
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null
+    const v = Number(part)
+    if (v > 255) return null
+    n = n * 256 + v
+  }
+  return n >>> 0
+}
+
+const cidrContains = (host, entry) => {
+  const [network, bitsRaw] = entry.split('/')
+  const bits = Number(bitsRaw)
+  const a = ipv4ToInt(host)
+  const b = ipv4ToInt(network)
+  if (a === null || b === null || !Number.isInteger(bits) || bits < 0 || bits > 32) return false
+  if (bits === 0) return true
+  const mask = (0xffffffff << (32 - bits)) >>> 0
+  return ((a & mask) >>> 0) === ((b & mask) >>> 0)
+}
+
+// NO_PROXY entries are hostnames, suffixes (`.corp.example`, `*.corp.example`),
+// `host:port`, an IPv4 CIDR, or `*` for everything. The CIDR form is here
+// because a corporate NO_PROXY nearly always carries one (10.0.0.0/8), and
+// tunnelling an internal host fails exactly as hard as not tunnelling an
+// external one.
+function noProxyMatches(hostname, port) {
+  const raw = noProxyEnv()?.value
+  if (!raw) return false
+  const host = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '')
+  for (const token of raw.split(/[,\s]+/)) {
+    if (!token) continue
+    if (token === '*') return true
+    let entry = token.toLowerCase()
+    // `host:port` — but never split a bare IPv6 literal on its own colons.
+    const withPort = /^(.+):(\d+)$/.exec(entry)
+    if (withPort && !withPort[1].includes(':')) {
+      if (withPort[2] !== String(port)) continue
+      entry = withPort[1]
+    }
+    if (entry.includes('/')) {
+      if (cidrContains(host, entry)) return true
+      continue
+    }
+    entry = entry.replace(/^\*?\./, '')
+    if (!entry) continue
+    if (host === entry || host.endsWith(`.${entry}`)) return true
+  }
+  return false
+}
+
+// A proxy variable we cannot parse is refused out loud. Ignoring it would put
+// us back exactly where this release started: a CLI dialling direct while the
+// partner believes their proxy is carrying the traffic.
+//
+// It throws rather than die()s. die() prints, and this runs inside the request
+// path AND inside egressHint() — so a bad variable printed its message three
+// times before the error it caused. One config problem, one line: the throw is
+// rendered once by whoever was making the call, and checked up front by
+// assertProxyEnvUsable() before any command runs.
+const proxyCache = new Map()
+function parseProxy(varName, raw) {
+  const cacheKey = `${varName} ${raw}`
+  if (proxyCache.has(cacheKey)) return proxyCache.get(cacheKey)
+  // `proxy.corp:8080`, with no scheme at all, is common enough to accept.
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`
+  let u = null
+  try { u = new URL(withScheme) } catch { u = null }
+  if (!u || !u.hostname) {
+    throw new Error(`${varName} is not a usable proxy URL ("${raw}") — expected http://host:port`)
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(
+      `${varName} names a ${u.protocol.replace(':', '')} proxy ("${raw}"), which this CLI cannot use. ` +
+        `Myelin speaks to an HTTP CONNECT proxy (http://host:port). Ask your network team for one, or for the ` +
+        `allowlist in the CLI README's "For your IT department" section.`,
+    )
+  }
+  const port = Number(u.port || (u.protocol === 'https:' ? 443 : 80))
+  const proxy = {
+    protocol: u.protocol,
+    hostname: u.hostname,
+    port,
+    // Credentials go on the wire and nowhere else: `display` is the only form
+    // a message, a log line or an error is allowed to carry.
+    auth: u.username
+      ? Buffer.from(`${decodeURIComponent(u.username)}:${decodeURIComponent(u.password)}`).toString('base64')
+      : null,
+    display: `${u.protocol}//${u.hostname}:${port}`,
+  }
+  proxyCache.set(cacheKey, proxy)
+  return proxy
+}
+
+function proxyForUrl(url) {
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+  if (noProxyMatches(url.hostname, port)) return null
+  const pair = url.protocol === 'https:' ? httpsProxyEnv() : httpProxyEnv()
+  return pair ? parseProxy(pair.name, pair.value) : null
+}
+
+// Checked before the first request rather than at the moment one fails: a typo
+// in HTTPS_PROXY deserves one clear line at the top, not a connection error
+// wearing a configuration error's clothes.
+function assertProxyEnvUsable() {
+  for (const pair of [httpsProxyEnv(), httpProxyEnv()]) {
+    if (!pair) continue
+    try { parseProxy(pair.name, pair.value) } catch (err) { die(err.message) }
+  }
+}
+
+const hostOf = (rawUrl) => {
+  try { return new URL(rawUrl).host } catch { return 'the storage host' }
+}
+
+// Which egress a failed call took, in one clause appended to the error. The
+// old message ("fetch failed") sent a proxied partner to us; naming the proxy
+// sends them to their network team, which is where the answer lives.
+function egressHint(rawUrl, message = '') {
+  let url = null
+  try { url = new URL(rawUrl) } catch { return '' }
+  let proxy = null
+  try { proxy = proxyForUrl(url) } catch { return '' }
+  if (proxy) return message.includes(proxy.display) ? '' : ` — via proxy ${proxy.display}`
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+  if (anyProxyEnv() && noProxyMatches(url.hostname, port)) {
+    return ` — connected directly: NO_PROXY excludes ${url.hostname}`
+  }
+  return ''
+}
+
+const directAgents = {
+  'http:': new http.Agent({ keepAlive: true }),
+  'https:': new https.Agent({ keepAlive: true }),
+}
+
+// CONNECT is where a misconfigured proxy hangs for ever — a blackholed SYN, or
+// a proxy that accepts the socket and then says nothing. Every other wait in
+// this file deliberately inherits fetch's "no timeout" (a 10 000-file
+// preflight legitimately takes minutes); a tunnel that has not opened in 30 s
+// is not opening.
+const TUNNEL_TIMEOUT_MS = 30_000
+
+function openTunnel(proxy, host, port) {
+  return new Promise((resolveSocket, reject) => {
+    const transport = proxy.protocol === 'https:' ? https : http
+    const req = transport.request({
+      host: proxy.hostname,
+      port: proxy.port,
+      method: 'CONNECT',
+      path: `${host}:${port}`,
+      agent: false,
+      headers: {
+        Host: `${host}:${port}`,
+        'User-Agent': UA,
+        ...(proxy.auth ? { 'Proxy-Authorization': `Basic ${proxy.auth}` } : {}),
+      },
+      ...(proxy.protocol === 'https:' ? { servername: proxy.hostname } : {}),
+    })
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      req.destroy()
+      reject(new Error(`proxy ${proxy.display} did not open a tunnel to ${host}:${port} within ${TUNNEL_TIMEOUT_MS / 1000}s`))
+    }, TUNNEL_TIMEOUT_MS)
+    timer.unref?.()
+    const settle = (fn) => (...a) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn(...a)
+    }
+    req.once('connect', settle((res, socket) => {
+      if (res.statusCode === 200) { resolveSocket(socket); return }
+      socket.destroy()
+      reject(new Error(
+        res.statusCode === 407
+          ? `proxy ${proxy.display} requires authentication (407) — put the credentials in the proxy URL (http://user:pass@host:port)`
+          : `proxy ${proxy.display} refused a tunnel to ${host}:${port} (HTTP ${res.statusCode})`,
+      ))
+    }))
+    // A proxy that answers CONNECT with an ordinary response — a captive
+    // portal, or an explicit proxy expecting absolute-form requests — is not
+    // going to tunnel anything. Say so rather than wait for the timeout.
+    req.once('response', settle((res) => {
+      res.resume()
+      reject(new Error(`proxy ${proxy.display} answered CONNECT with HTTP ${res.statusCode} instead of opening a tunnel to ${host}:${port}`))
+    }))
+    req.once('error', settle((err) => reject(new Error(`proxy ${proxy.display}: ${err.message}`))))
+    req.end()
+  })
+}
+
+// One tunnelling agent per proxy. keepAlive is OFF on this path on purpose: a
+// pooled socket here is a CONNECT tunnel the proxy may have torn down while it
+// sat idle, and the next part upload would then fail on a socket that still
+// looked healthy. One handshake per request, against a 64 MB part, is noise.
+class TunnelAgent extends https.Agent {
+  constructor(proxy) {
+    super({ keepAlive: false })
+    this.proxy = proxy
+  }
+  createConnection(options, cb) {
+    openTunnel(this.proxy, options.host, options.port).then(
+      (socket) => cb(null, tls.connect({ socket, servername: options.servername || options.host })),
+      (err) => cb(err),
+    )
+  }
+}
+const tunnelAgents = new Map()
+const tunnelAgentFor = (proxy) => {
+  const key = `${proxy.display} ${proxy.auth ?? ''}`
+  let agent = tunnelAgents.get(key)
+  if (!agent) {
+    agent = new TunnelAgent(proxy)
+    tunnelAgents.set(key, agent)
+  }
+  return agent
+}
+
+// Bodies: a string, a Buffer, or a FormData (the sandbox upload). Multipart is
+// not hand-rolled — `Response` is a global, so letting the platform encode the
+// FormData costs no dependency and cannot disagree with what a server expects.
+async function encodeBody(body) {
+  if (body == null) return { bytes: null, contentType: null }
+  if (typeof body === 'string') return { bytes: Buffer.from(body, 'utf8'), contentType: null }
+  if (Buffer.isBuffer(body)) return { bytes: body, contentType: null }
+  if (ArrayBuffer.isView(body)) return { bytes: Buffer.from(body.buffer, body.byteOffset, body.byteLength), contentType: null }
+  const encoded = new Response(body)
+  return { bytes: Buffer.from(await encoded.arrayBuffer()), contentType: encoded.headers.get('content-type') }
+}
+
+function decodeBody(raw, encoding) {
+  const enc = String(encoding ?? '').trim().toLowerCase()
+  try {
+    if (enc === 'gzip' || enc === 'x-gzip') return zlib.gunzipSync(raw).toString('utf8')
+    if (enc === 'br') return zlib.brotliDecompressSync(raw).toString('utf8')
+    if (enc === 'deflate') {
+      try { return zlib.inflateSync(raw).toString('utf8') } catch { return zlib.inflateRawSync(raw).toString('utf8') }
+    }
+  } catch {
+    // A body we cannot inflate is still worth showing raw — half an error
+    // message beats none.
+  }
+  return raw.toString('utf8')
+}
+
+// The whole HTTP surface of this CLI, in one function. It returns the small
+// slice of the fetch Response shape the rest of the file uses — `status`,
+// `headers.get()`, `json()`, `text()` — so the call sites read as they did.
+async function httpRequest(rawUrl, { method = 'GET', headers = {}, body } = {}, redirectsLeft = 5) {
+  const url = new URL(rawUrl)
+  const proxy = proxyForUrl(url)
+  const { bytes, contentType } = await encodeBody(body)
+
+  const sent = {}
+  for (const [k, v] of Object.entries(headers)) if (v != null) sent[k.toLowerCase()] = String(v)
+  sent['user-agent'] ??= UA
+  sent['accept-encoding'] ??= 'gzip, deflate, br'
+  if (bytes) {
+    // ⚠ Always a Content-Length, never chunked: S3 rejects a chunked PUT, and
+    // a presigned part upload is the one request here that must never be
+    // refused for a transport reason.
+    sent['content-length'] = String(bytes.length)
+    if (contentType && !sent['content-type']) sent['content-type'] = contentType
+  }
+
+  // https through a proxy is a CONNECT tunnel; plain http through a proxy is
+  // an absolute-form request line addressed to the proxy itself.
+  const tunnelled = Boolean(proxy) && url.protocol === 'https:'
+  const forwarded = Boolean(proxy) && url.protocol === 'http:'
+  if (forwarded) {
+    sent.host = url.host
+    if (proxy.auth) sent['proxy-authorization'] = `Basic ${proxy.auth}`
+  }
+  const transport = (forwarded ? proxy.protocol : url.protocol) === 'https:' ? https : http
+  const options = forwarded
+    ? { host: proxy.hostname, port: proxy.port, method, path: url.href, headers: sent, agent: directAgents[proxy.protocol] }
+    : {
+        host: url.hostname,
+        port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)),
+        method,
+        path: `${url.pathname}${url.search}`,
+        headers: sent,
+        agent: tunnelled ? tunnelAgentFor(proxy) : directAgents[url.protocol],
+      }
+
+  return new Promise((settle, reject) => {
+    const req = transport.request(options, (res) => {
+      // 407 is a proxy's status, never an origin server's. On the forwarded
+      // path it arrives as an ordinary response, so without this the CLI
+      // reported it as though Myelin had answered — "[error] HTTP 407" and a
+      // partner reading it as our problem. The tunnel path already says this
+      // properly; both now do.
+      if (forwarded && res.statusCode === 407) {
+        res.resume()
+        reject(new Error(`proxy ${proxy.display} requires authentication (407) — put the credentials in the proxy URL (http://user:pass@host:port)`))
+        return
+      }
+      const location = res.headers.location
+      if (location && [301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0) {
+        res.resume()
+        let next = null
+        try { next = new URL(location, url) } catch { next = null }
+        if (next) {
+          const toGet = res.statusCode === 303 || ([301, 302].includes(res.statusCode) && method !== 'GET' && method !== 'HEAD')
+          const forward = {}
+          for (const [k, v] of Object.entries(headers)) {
+            // The rule fetch follows, and the one that matters here: a bearer
+            // token does not cross an origin. A front door that bounces us to
+            // an identity provider must never be handed the API key.
+            if (next.origin !== url.origin && k.toLowerCase() === 'authorization') continue
+            forward[k] = v
+          }
+          settle(httpRequest(next.href, { method: toGet ? 'GET' : method, headers: forward, body: toGet ? undefined : body }, redirectsLeft - 1))
+          return
+        }
+      }
+      const chunks = []
+      res.on('data', (c) => chunks.push(c))
+      res.on('error', reject)
+      res.on('end', () => {
+        const text = decodeBody(Buffer.concat(chunks), res.headers['content-encoding'])
+        settle({
+          status: res.statusCode,
+          headers: {
+            get: (name) => {
+              const v = res.headers[String(name).toLowerCase()]
+              return v == null ? null : Array.isArray(v) ? v.join(', ') : v
+            },
+          },
+          text: async () => text,
+          json: async () => JSON.parse(text),
+        })
+      })
+    })
+    req.once('error', reject)
+    if (bytes) req.end(bytes)
+    else req.end()
+  })
+}
+
 // 429s are handled HERE so every command inherits the platform's documented
 // contract (honour Retry-After): bounded — 4 waits, then the error surfaces
 // like any other. The wait is capped at 60 s so a pathological header cannot
 // stall a pipeline for an hour.
 async function api(method, path, body, raw) {
   for (let attempt = 1; ; attempt++) {
-    const res = await fetch(API_URL + path, {
+    const res = await httpRequest(API_URL + path, {
       method,
       headers: {
         ...EXTRA_HEADERS,
@@ -168,7 +576,7 @@ async function api(method, path, body, raw) {
         ...(body && !raw ? { 'Content-Type': 'application/json' } : {}),
       },
       body: raw ? body : body ? JSON.stringify(body) : undefined,
-    }).catch((err) => die(`Cannot reach ${API_URL}: ${err.message}`))
+    }).catch((err) => die(`Cannot reach ${API_URL}: ${err.message}${egressHint(API_URL, err.message)}`))
     let json = null
     try { json = await res.json() } catch { /* non-JSON body */ }
     const requestId = res.headers.get('myelin-request-id') ?? json?.request_id ?? null
@@ -452,10 +860,19 @@ async function uploadFileParts(absPath, size, fileId, partSize, adoptLandedGeome
           if (url === undefined) url = await resign(partNo, bytes)
           if (url === null) break // part landed server-side — resign() recorded its etag
           const startedAt = Date.now()
-          put = await fetch(url, { method: 'PUT', body: bytes }).catch(() => null)
+          let netErr = null
+          put = await httpRequest(url, { method: 'PUT', body: bytes }).catch((err) => { netErr = err; return null })
           if (put && put.status === 200) break
           const status = put ? put.status : 0
-          const reason = put ? `HTTP ${put.status}` : 'network error'
+          // ⚠ Never print `url` itself — a presigned URL carries its
+          // authorization in the query string. The HOST is the part a partner
+          // needs: a firewall or proxy that allows the API host and not the
+          // storage host is the commonest way a delivery dies, and the old
+          // bare "network error" sent them to look at Myelin instead of at
+          // their own egress.
+          const reason = put
+            ? `HTTP ${put.status}`
+            : `network error reaching ${hostOf(url)}${netErr ? ` (${netErr.message})` : ''}${egressHint(url, netErr?.message ?? '')}`
           if (isTimeoutClassFailure(status, Date.now() - startedAt)) {
             const strikes = (timeoutStrikes.get(partNo) ?? 0) + 1
             timeoutStrikes.set(partNo, strikes)
@@ -496,6 +913,12 @@ async function cmdPing() {
   const j = expectOk(await api('GET', '/ping'), 'ping')
   emit(j)
   out(`✓ key "${j.key.name}" (${j.key.prefix}…) · bridge ${j.bridge.name} · ${j.projects.length} project(s)`)
+  // The first question an IT department asks once a proxy is in play: is the
+  // CLI actually going through it? Printed only when one applies, so the
+  // ordinary output is unchanged.
+  const via = proxyForUrl(new URL(API_URL))
+  if (via) out(`  via proxy ${via.display}`)
+  out('Next: myelin datasets')
 }
 
 async function cmdProjects() {
@@ -522,11 +945,19 @@ async function cmdDatasets() {
   }
   emit({ datasets: rows })
   if (!JSON_MODE) {
+    if (rows.length === 0) {
+      // The commonest first-run dead end, and nothing on the partner's side
+      // fixes it: the client has not activated a dataset in a project this
+      // key is scoped to. Say so, rather than printing an empty table.
+      out('No dataset to deliver to yet. The client activates one on their side, in a project this key is scoped to — ask your client contact.')
+      return
+    }
     const lines = table(
       ['PROJECT', 'DATASET', 'STATUS', 'YOUR MOVE?'],
       rows.map((r) => [r.project, r.dataset, r.status, r.open_draft ? 'yes — open draft to finish' : '—']),
     )
     for (const line of lines) out(line)
+    out(`Next: myelin contract --dataset ${rows[0].dataset}`)
   }
 }
 
@@ -576,8 +1007,11 @@ async function cmdContract() {
       // was not `blocking` a "should", so a `must_acknowledge` rule — the one
       // that demands a named decision from the reviewer — printed identically
       // to a warning nobody has to read.
+      // `?` is what `check` and `status` print for "not checked"; the reviewer-
+      // confirmed rung gets its own glyph so one mark means one thing across
+      // the three commands (first-contact review, 2026-09-19).
       const mark =
-        c.severity === 'blocking' ? '!' : c.severity === 'must_acknowledge' ? '?' : '·'
+        c.severity === 'blocking' ? '!' : c.severity === 'must_acknowledge' ? '~' : '·'
       const when = c.runs_at === 'preflight' ? '' : ' (checked at submission)'
       const note =
         c.severity === 'must_acknowledge'
@@ -735,8 +1169,10 @@ async function cmdCheck() {
   // true, and the coverage is stated the rest of the time — framed as a
   // capability to gain, because it is one: more checks running before you send
   // means fewer rejections after.
+  const next = `Next: myelin push ${dir} --dataset ${dsRef} --submit`
   if (!k || k.passed + k.not_applicable === k.evaluated) {
     out('All checks that run before upload pass.')
+    out(next)
     return
   }
   const rest = []
@@ -746,6 +1182,7 @@ async function cmdCheck() {
   if (k.not_evaluated > 0) {
     out(`Supply what ${k.not_evaluated === 1 ? 'it needs' : 'they need'} and ${k.not_evaluated === 1 ? 'it runs' : 'they run'} on your next delivery.`)
   }
+  out(next)
 }
 
 async function cmdPush() {
@@ -782,7 +1219,10 @@ async function cmdPush() {
   }
   const created = expectOk(createRes, 'create batch')
   const batchId = created.batch_id
-  out(`Draft ${created.resumed ? 'resumed' : 'created'} (${batchId.slice(0, 8)}…).`)
+  // The display name (ONCO1-WES-004) is what a person passes to `status` and
+  // `recall`; the create call answers with the id only, so read it once.
+  const batchName = (await api('GET', `/batches/${batchId}`)).json?.batch?.display_name ?? batchId
+  out(`Draft ${batchName} ${created.resumed ? 'resumed' : 'created'}.`)
 
   // 2. declare in chunks of 500 — idempotent, so re-running skips what's done
   const declared = []
@@ -845,7 +1285,7 @@ async function cmdPush() {
     if (j.already_submitted) {
       // A retried submit whose first attempt actually landed: the API echoes
       // success instead of failing, and so do we — nothing to redo.
-      out(`✓ Batch already submitted (${j.status}) — nothing to redo. Track: myelin status ${batchId} --watch`)
+      out(`✓ Batch already submitted (${j.status}) — nothing to redo. Track: myelin status ${batchName} --watch`)
     } else {
       // ⚠ This line used to print three numbers and no denominator, which was
       // exhaustive until the engine could abstain — after that, an abstention
@@ -863,7 +1303,7 @@ async function cmdPush() {
       if (a.must_acknowledge_failures) {
         out(`  ${a.must_acknowledge_failures} check(s) your client asked to be told about — nothing to fix.`)
       }
-      out(`✓ Batch submitted for review. Track: myelin status ${batchId} --watch`)
+      out(`✓ Batch submitted for review. Track: myelin status ${batchName} --watch`)
     }
   } else {
     emit({ batch_id: batchId, files: declared.length, submitted: false })
@@ -871,27 +1311,53 @@ async function cmdPush() {
   }
 }
 
+// A batch by id or by display name (`ONCO1-WES-004`), as `push` prints it.
+// Shared by `status` and `recall`.
+async function resolveBatch(ref) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
+    const r = await api('GET', `/batches/${ref}`)
+    if (r.status === 200) return expectOk(r, 'batch').batch
+    die(`Batch ${ref} not found in this key's scope`)
+  }
+  // Paged: a key that has delivered more than a hundred times still finds
+  // its batch by name.
+  let cursor = null
+  for (;;) {
+    const list = expectOk(
+      await api('GET', `/batches?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`),
+      'batches',
+    )
+    const hit = list.batches.find((b) => b.display_name === ref)
+    if (hit) return expectOk(await api('GET', `/batches/${hit.id}`), 'batch').batch
+    if (!list.next_cursor) die(`No batch named "${ref}" in this key's scope`)
+    cursor = list.next_cursor
+  }
+}
+
 async function cmdStatus() {
   const ref = args[1]
-  if (!ref) die('Usage: myelin status <batch-id|display-name> [--watch]')
+  // `myelin status --watch` used to take "--watch" as the batch name and go
+  // to the network with it; a flag is never a batch.
+  if (!ref || ref.startsWith('--')) die('Usage: myelin status <batch-id|display-name> [--watch]')
 
-  const findBatch = async () => {
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
-      const r = await api('GET', `/batches/${ref}`)
-      if (r.status === 200) return expectOk(r, 'batch').batch
-      die(`Batch ${ref} not found in this key's scope`)
-    }
-    const list = expectOk(await api('GET', '/batches?limit=100'), 'batches')
-    const hit = list.batches.find((b) => b.display_name === ref)
-    if (!hit) die(`No batch named "${ref}" in this key's scope`)
-    return expectOk(await api('GET', `/batches/${hit.id}`), 'batch').batch
-  }
+  const findBatch = () => resolveBatch(ref)
 
   const print = async (batch) => {
-    emit({ batch })
-    out(`${batch.display_name}: ${batch.status} — ${batch.court === 'partner' ? 'your move.' : batch.court === 'reviewer' ? "reviewer's move." : batch.court === 'system' ? 'transferring…' : 'done.'}`)
+    // "done." used to cover rejected and transfer_failed alike. A final state
+    // says what it is; the rest says whose move it is.
+    const tail =
+      batch.status === 'transferred' ? 'delivered to your client’s bucket.'
+      : batch.status === 'rejected' ? 'rejected — final.'
+      : batch.status === 'transfer_failed' ? 'transfer failed on the Myelin side — nothing to redo; ask your client contact.'
+      : batch.court === 'partner' ? 'your move.'
+      : batch.court === 'reviewer' ? "reviewer's move."
+      : batch.court === 'system' ? 'transferring…'
+      : 'done.'
+    out(`${batch.display_name}: ${batch.status} — ${tail}`)
+    let findings = null
     if (batch.status === 'changes_requested') {
       const f = expectOk(await api('GET', `/batches/${batch.id}/findings`), 'findings')
+      findings = f
       if (f.request_changes_comment) out(`  reviewer: "${f.request_changes_comment}"`)
       for (const fr of f.file_reviews.filter((x) => x.verdict === 'failed')) {
         out(`  ✗ ${fr.path}  (${fr.reviewer ?? 'reviewer'}: ${fr.comment ?? 'failed'})`)
@@ -914,20 +1380,55 @@ async function cmdStatus() {
         )
       }
     }
+    emit(findings ? { batch, findings } : { batch })
     return batch
   }
 
   let batch = await print(await findBatch())
   if (flag('watch')) {
+    // Nothing to wait for on a draft: it is the partner's own move.
+    if (batch.status === 'draft') {
+      out('  nothing to wait for — it is your move: myelin push <dir> --dataset <ds> --submit')
+      process.exitCode = 2
+      return
+    }
     const terminal = ['transferred', 'rejected', 'changes_requested', 'transfer_failed']
+    let misses = 0
     while (!terminal.includes(batch.status)) {
       await new Promise((r) => setTimeout(r, 20_000))
-      const next = await findBatch()
+      let next
+      try {
+        next = await findBatch()
+        misses = 0
+      } catch (err) {
+        // A network blip mid-watch used to end the command with exit 1 after
+        // hours of polling. Five consecutive misses is a real outage.
+        if (!(err instanceof CliExit) || ++misses >= 5) throw err
+        process.exitCode = 0
+        out(`  (could not reach the API — retrying, ${misses}/5)`)
+        continue
+      }
       if (next.status !== batch.status) batch = await print(next)
     }
+    // A pipeline branches on the exit code: 0 delivered, 2 your move, 1 final.
+    if (batch.status === 'changes_requested') process.exitCode = 2
+    else if (batch.status === 'rejected' || batch.status === 'transfer_failed') process.exitCode = 1
   }
 }
 
+// Take a submitted delivery back before the review starts. The page and the
+// API's own `delivery_locked` message both said "recall it" while the CLI had
+// no way to (first-contact review, 2026-09-19).
+async function cmdRecall() {
+  const ref = args[1]
+  if (!ref || ref.startsWith('--')) die('Usage: myelin recall <batch-id|display-name>')
+  const batch = await resolveBatch(ref)
+  const r = await api('POST', `/batches/${batch.id}/recall`)
+  if (r.status !== 200) apiDie('recall', r)
+  emit(r.json)
+  out(`✓ ${batch.display_name} recalled — it is a draft again (${r.json.status}). Fix, then: myelin push <dir> --dataset <ds> --submit`)
+}
+
 async function cmdSandbox() {
   const file = args[1]
   if (!file) die('Usage: myelin sandbox <file>')
@@ -984,6 +1485,10 @@ async function cmdRoles() {
   if (sub === 'set' || sub === 'none' || sub === 'clear') {
     const role = args[2]
     if (!role) die(`Usage: myelin roles ${sub} <role>${sub === 'set' ? ' <path>' : ''} --dataset <slug|id>`)
+    // A misspelt role used to travel to the API and come back as a 400; the
+    // five names are known here.
+    const KNOWN_ROLES = ['samplesheet', 'checksum_manifest', 'qc_report', 'subject_roster', 'capture_bed']
+    if (!KNOWN_ROLES.includes(role)) die(`Unknown role "${role}" — one of ${KNOWN_ROLES.join(', ')}`)
     const body = { role }
     if (sub === 'set') {
       const path = args[3]
@@ -1033,37 +1538,193 @@ async function cmdRoles() {
   }
 }
 
-function cmdHelp() {
-  console.log(`myelin — Partner Ingestion CLI
+// ——— help ———
+//
+// Two doors, both open WITHOUT a key: `myelin help [<command>]` and
+// `myelin <command> --help`. The developer reading this is usually waiting for
+// a key from the bridge owner, and the manual is the one thing they can use
+// meanwhile. The overview lists the commands in the order a first delivery
+// runs them, so the list is also the path. No version numbers anywhere in this
+// text: a change ships as the current behaviour, not as a diff against a past
+// no partner has lived (founder, 2026-09-19). `scripts/test-cli-docs.ts` holds
+// this text, the README's table and the /developers table to the same set of
+// commands, and fails on a semver literal in any of them.
+
+const HELP = {
+  ping: {
+    usage: 'myelin ping',
+    what: 'Checks the key and prints the bridge it belongs to and the projects it can reach.',
+    notes: [
+      'Run this first. If it succeeds but `datasets` prints nothing, the client has not',
+      'activated a dataset yet — nothing on your side fixes that; ask your client contact.',
+    ],
+  },
+  datasets: {
+    usage: 'myelin datasets',
+    what: 'Lists the datasets you can deliver to, and whose move it is on each.',
+    notes: [
+      'DATASET is the slug you pass to --dataset (any case). "YOUR MOVE? yes" means a',
+      'draft of yours is open and waiting to be finished or submitted.',
+    ],
+  },
+  contract: {
+    usage: 'myelin contract --dataset <ds>',
+    what: 'Prints what the client expects of a delivery: every check, one sentence each.',
+    notes: [
+      '  !  blocks validation if it fails',
+      '  ~  is confirmed by the client’s reviewer, never fixed by you',
+      'Also says which checks `check` can run locally and which run once the files are up,',
+      'and the client’s own fields on the dataset (read-only, informational).',
+    ],
+  },
+  check: {
+    usage: 'myelin check <dir> --dataset <ds>',
+    what: 'Runs the dataset’s checks on your local folder, server-side, without uploading a byte.',
+    notes: [
+      'Exit 2 when a blocking check failed OR could not be evaluated — both stop the',
+      'reviewer validating. Checks that read file contents run at submit; they are listed',
+      'as deferred here. Safe to run as often as you like.',
+    ],
+  },
+  push: {
+    usage: 'myelin push <dir> --dataset <ds> [--submit] [--replace]',
+    what: 'Creates or resumes the dataset’s draft and uploads what has not landed yet.',
+    notes: [
+      '--submit   hand the delivery over for review once every file is up',
+      '--replace  overwrite a path already declared with a different size or checksum',
+      '           (without it, that path exits 2)',
+      'Every file under <dir> is sent, dotfiles included, symlinks followed; a broken link',
+      'or an unreadable file stops the command and is named. Stage a clean folder if your',
+      'pipeline leaves work files behind.',
+      'Re-run the same command to resume: uploaded files, and uploaded parts of a large',
+      'file, are skipped. One draft per dataset; without --submit it stays open, and a',
+      'later push of a DIFFERENT folder joins that same draft. While a delivery is',
+      'submitted or in review, push to that dataset exits 2 (delivery_locked).',
+      'push does not run check first — run check yourself. At the end it prints the',
+      'delivery name (ONCO1-WES-004) that `status` and `recall` take.',
+    ],
+  },
+  status: {
+    usage: 'myelin status <batch> [--watch]',
+    what: 'Where a delivery stands and whose move it is. Takes an id or a display name.',
+    notes: [
+      'On changes_requested: the files the reviewer flagged, their comments, and a hint',
+      'per failed rule. Fix, then `push --submit` again — untouched files keep their votes.',
+      '--watch polls every 20 s and returns at the first final state, with an exit code',
+      'a script can branch on: 0 transferred · 2 changes_requested (your move) ·',
+      '1 rejected or transfer_failed. A network blip mid-watch is retried five times.',
+      'A review can take days: for an unattended job prefer a webhook (see /developers).',
+      'In --json, changes_requested carries the findings too.',
+    ],
+  },
+  recall: {
+    usage: 'myelin recall <batch>',
+    what: 'Takes a submitted delivery back before the review starts. It becomes a draft again.',
+    notes: [
+      'Only while the status is submitted. Once a reviewer has opened it (in_review) the',
+      'API answers recall_failed; wait for their decision instead.',
+    ],
+  },
+  projects: {
+    usage: 'myelin projects',
+    what: 'Lists the projects this key is scoped to, with their status.',
+    notes: [],
+  },
+  'sample-depth': {
+    usage: 'myelin sample-depth <0-5> --dataset <ds>',
+    what: 'Declares the folder depth a sample sits at. Optional; the default is 1.',
+    notes: [
+      '  0  the delivery root is one sample',
+      '  1  each top-level folder is one sample (default)',
+      '  2  one level deeper, and so on',
+      'Set it only if the default is wrong for your layout. Idempotent; it locks once your',
+      'first delivery leaves draft, so per-sample verdicts stay comparable.',
+    ],
+  },
+  roles: {
+    usage: 'myelin roles [set <role> <path> | none <role> | clear <role>] --dataset <ds>',
+    what: 'Shows, declares or clears which file plays which role. Optional; never locks.',
+    notes: [
+      'Roles: samplesheet, checksum_manifest, qc_report, subject_roster, capture_bed.',
+      'Nothing is required to deliver. Declaring a role turns on the checks that read',
+      'that file, so more of the contract is verified before review. `none` records that',
+      'your dataset has no such file. Idempotent — safe to assert on every run.',
+    ],
+  },
+  sandbox: {
+    usage: 'myelin sandbox <file>',
+    what: 'Uploads one file under 4 MB as the partner-side test transfer your client’s bridge-activation checklist asks for.',
+    notes: ['It proves the route works. Not a test environment, and not a step before push.'],
+  },
+  deliveries: {
+    usage: 'myelin deliveries [--project <id>] [--dataset <id>] [--since <iso>] [--limit <n>] [--cursor <ts>]',
+    what: 'What landed in your bucket, newest first. Needs a CLIENT key (Organisation → API keys).',
+    notes: ['Page with --cursor, passing back the printed next_cursor verbatim.'],
+  },
+  resolve: {
+    usage: 'myelin resolve <path|prefix|id>',
+    what: 'What a path in your bucket is: project, dataset, delivery, file. Needs a CLIENT key.',
+    notes: ['Accepts a gs:// or s3:// URI, a bare prefix, or a single id.'],
+  },
+  version: {
+    usage: 'myelin version',
+    what: 'Prints the CLI version.',
+    notes: [],
+  },
+  help: {
+    usage: 'myelin help [<command>]',
+    what: 'This list, or one command in detail. Works without a key.',
+    notes: [],
+  },
+}
 
-Setup:
-  export MYELIN_API_KEY=myl_live_…        (create in Bridge → API)
-  export MYELIN_API_URL=…                 (optional; default https://myelinbridge.com/api/v1)
-  export MYELIN_API_HEADER="Name: value"  (optional; extra headers, one per line —
-                                           for a gateway that authenticates ahead of Myelin)
-
-Commands:
-  ping                                    verify the key; show bridge + projects
-  projects                                list scoped projects
-  datasets                                list datasets with "your move" hints
-  sample-depth <0-5> --dataset <slug|id>  declare the folder depth a sample sits at (locks after 1st submit)
-  roles [set|none|clear …] --dataset <…>  which file plays each role (samplesheet, checksum list, …) —
-                                          declaring one activates the checks that read it; never locks
-  contract --dataset <slug|id>            what this dataset expects of your delivery
-  check <dir> --dataset <slug|id>         preflight local files against quality rules (no upload)
-  push <dir> --dataset <slug|id>          create/resume a delivery and upload (resumable; re-run to resume)
-       [--submit] [--replace]
-  status <batch|name> [--watch]           review status + fix-loop findings
-  sandbox <file>                          partner-side test transfer (bridge activation)
-
-Client-side commands (need a CLIENT key — Organisation → API keys):
-  deliveries [--project <id>]             what landed in your destination bucket
-             [--dataset <id>] [--since <iso>] [--limit <n>] [--cursor <ts>]
-  resolve <path|prefix|id>                what a path in your bucket actually is —
-                                          project, dataset, batch, file
+function cmdHelp(name) {
+  if (name && !HELP[name]) die(`Unknown command "${name}" — run: myelin help`)
+  // "Every command accepts --json" includes this one.
+  if (JSON_MODE) {
+    emit(name ? { command: name, ...HELP[name] } : { commands: HELP })
+    return
+  }
+  if (name) {
+    const h = HELP[name]
+    console.log(`Usage: ${h.usage}\n\n${h.what}${h.notes.length ? '\n\n' + h.notes.join('\n') : ''}`)
+    return
+  }
+  console.log(`myelin — deliver R&D data to your client through Myelin
+
+Usage: myelin <command> [--json]
+       myelin help <command>
+
+Commands, in the order a first delivery runs them:
+  ping                                    the key works, and what it can reach
+  datasets                                what you can deliver to, and whose move it is
+  contract --dataset <ds>                 what the client expects of a delivery
+  check <dir> --dataset <ds>              their checks on your folder — nothing is uploaded
+  push <dir> --dataset <ds> [--submit]    upload (resumable, re-run to resume), then hand over
+  status <batch> [--watch]                follow the review; on changes_requested, what to fix
+
+Optional:
+  recall <batch>                          take a submitted delivery back before review starts
+  projects                                the projects this key is scoped to
+  sample-depth <0-5> --dataset <ds>       the folder depth a sample sits at (default 1)
+  roles … --dataset <ds>                  which file plays which role; turns on more checks
+  sandbox <file>                          the connectivity test bridge activation asks for
+
+Client-side commands (a CLIENT key, from Organisation → API keys):
+  deliveries                              what landed in your bucket
+  resolve <path|prefix|id>                what a path in your bucket is
 
   version                                 print the CLI version
+  help [<command>]                        this list, or one command in detail
+
+Setup:
+  export MYELIN_API_KEY=myl_live_…        the key your bridge owner created in Bridge → API
+  export MYELIN_API_URL=…                 optional; default https://myelinbridge.com/api/v1
+  export MYELIN_API_HEADER="Name: value"  optional; extra headers, one per line, for a gateway
+                                          that authenticates ahead of Myelin
+  export HTTPS_PROXY=http://proxy:8080    optional; HTTP_PROXY / NO_PROXY honoured too
 
+<ds> is a dataset slug (any case), an id, or an exact name, as \`datasets\` prints them.
 Every command accepts --json. Exit codes: 0 ok · 1 error · 2 blocked.
 Errors print the API request id — include it when reporting a problem.`)
 }
@@ -1140,15 +1801,14 @@ async function cmdResolve() {
 }
 
 // ——— main ———
-if (!command || command === 'help' || command === '--help') {
-  cmdHelp()
-  process.exit(0)
-}
-if (command === 'version' || command === '--version' || command === '-v') {
-  console.log(JSON_MODE ? JSON.stringify({ version: VERSION }) : VERSION)
-  process.exit(0)
-}
-
+//
+// Order matters, and it is the order a developer without a key needs: help
+// and version answer before the key is looked at, an unknown command is
+// reported as unknown rather than as a missing key, and only a real command
+// about to call the API asks for MYELIN_API_KEY. The previous order checked
+// the key first, so `myelin push --help` and `myelin upload ./x` both answered
+// "Set MYELIN_API_KEY" — the manual was closed to exactly the person waiting
+// for a key (2026-09-19).
 const commands = {
   ping: cmdPing,
   projects: cmdProjects,
@@ -1159,15 +1819,70 @@ const commands = {
   check: cmdCheck,
   push: cmdPush,
   status: cmdStatus,
+  recall: cmdRecall,
   sandbox: cmdSandbox,
   deliveries: cmdDeliveries,
   resolve: cmdResolve,
 }
-try {
-  if (!KEY) die('Set MYELIN_API_KEY (create a key in Bridge → API).')
+
+// The options each command accepts. Anything else spelled `--…` is an error
+// before a byte moves: `push --sumbit` used to upload, not submit, and exit 0
+// — a green CI job that delivered nothing (first-contact review, 2026-09-19).
+// `--json`, `--help` and `-h` are global and handled before this table.
+const OPTIONS = {
+  ping: [],
+  projects: [],
+  datasets: [],
+  'sample-depth': ['dataset'],
+  roles: ['dataset'],
+  contract: ['dataset'],
+  check: ['dataset'],
+  push: ['dataset', 'submit', 'replace'],
+  status: ['watch'],
+  recall: [],
+  sandbox: [],
+  deliveries: ['project', 'dataset', 'since', 'limit', 'cursor'],
+  resolve: [],
+}
+
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') return cmdHelp(args[1])
+  if (flag('help') || args.includes('-h')) return cmdHelp(command)
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(JSON_MODE ? JSON.stringify({ version: VERSION }) : VERSION)
+    return
+  }
   const fn = commands[command]
   if (!fn) die(`Unknown command "${command}" — run: myelin help`)
+  const stray = args.slice(1).find((a) => a.startsWith('--') && !OPTIONS[command].includes(a.slice(2)))
+  if (stray) die(`Unknown option "${stray}" for ${command} — run: myelin help ${command}`)
+  // Usage before the key: `myelin push` with nothing else used to answer
+  // "MYELIN_API_KEY is not set" instead of saying what push takes.
+  const NEEDS = {
+    contract: { dataset: true },
+    check: { positional: true, dataset: true },
+    push: { positional: true, dataset: true },
+    'sample-depth': { positional: true, dataset: true },
+    roles: { dataset: true },
+    status: { positional: true },
+    recall: { positional: true },
+    sandbox: { positional: true },
+    resolve: { positional: true },
+  }[command]
+  if (NEEDS) {
+    const positional = args[1]
+    const missingPositional = NEEDS.positional && (!positional || positional.startsWith('--'))
+    if (missingPositional || (NEEDS.dataset && !opt('dataset'))) die(`Usage: ${HELP[command].usage}`)
+  }
+  // The first error every partner sees. It used to say "create a key in
+  // Bridge → API" — an instruction to the one person who cannot do that.
+  if (!KEY) die('MYELIN_API_KEY is not set. Your client creates the key for you (Bridge → API, on their side) and sends it. `myelin help` works without one.')
+  assertProxyEnvUsable()
   await fn()
+}
+
+try {
+  await main()
 } catch (err) {
   // die() already printed and set the code; anything else is a real bug and
   // deserves its stack.