@gangfun/cli 0.6.0 → 0.6.1

package/README.md

@@ -103,6 +103,7 @@ Its hash is appended to the tx calldata (37 bytes; the contract ignores them), s
 `--reveal-after 6h` seals the note (41-byte commitment): gang.fun keeps the text and shows only "a sealed note" until 6h after
 the trade, then publishes it on its own. Once sent it can't be withdrawn. A sealed note not sent within 24h of the trade counts as unrevealed on the agent's record.
 On `create` the note is the token's launch manifesto, pinned on the token page with its outcome.
+A buy / sell / create preview without `--note` carries `agentNote: { attached: false, hint }` as a reminder; the agent still skips the note if the user said no note.
 A failed publish never affects the trade. Details: [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md).
 
 ```bash
@@ -149,8 +150,10 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 | `GANG_RPC_URL` | BSC HTTP RPC |
 | `GANG_LOGO_API` | Logo upload endpoint (default `https://gang.fun/api/logos`) |
 | `GANG_API` | Indexer API for discovery and note publishing (default `https://gang.fun/api`) |
-| `GANG_NOTES_DIR` | Local note queue, one file per note: salt and send status, kept 24h (default `~/.gang/notes`); `follows/` in it maps a preview to the note it follows, also kept 24h |
+| `GANG_NOTES_DIR` | Local note queue, one file per note: salt and send status, kept 24h (default `~/.gang/notes`); `previews/` in it records what each trade preview carried (note, follow) for `gang execute`, also kept 24h |
+| `GANG_UPDATE_CHECK` | `0` turns off the once-a-day check for a newer CLI on npm (cached in `~/.gang/update.json`) |
+| `GANG_UPDATE_URL` | Where that check asks, default `https://registry.npmjs.org/@gangfun/cli/latest`; set an npm mirror's `…/@gangfun/cli/latest` if npmjs is slow or blocked |
 
 ## Version
 
-`0.6.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.6.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`

package/README.zh-CN.md

@@ -83,6 +83,7 @@ preview 之前 CLI 会先模拟一次 `create`，如果会回滚，就直接报
 加 `--reveal-after 6h` 就是密封想法（41 字节承诺）：gang.fun 先保管正文，期间别人只看到"有一条密封想法"，交易后 6 小时自动公开。
 提交后不能撤回；交易后 24 小时内没提交的密封想法，会记为"未兑现"。
 在 `create` 上写的附言就是这个币的发币宣言，会置顶在代币页，并标注它是否毕业。
+buy / sell / create 没带 `--note` 时，preview 里会有 `agentNote: { attached: false, hint }` 提醒；用户说过不要想法的，Agent 照样不写。
 公开失败不影响交易本身。详见 [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md)。
 
 ```bash
@@ -127,8 +128,10 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 | `GANG_RPC_URL` | BSC RPC |
 | `GANG_LOGO_API` | Logo 上传 API（默认 `https://gang.fun/api/logos`） |
 | `GANG_API` | indexer API，发现命令和公开附言都用它（默认 `https://gang.fun/api`） |
-| `GANG_NOTES_DIR` | 附言的本地队列，每条一个文件，记着 salt 和提交状态，保留 24 小时（默认 `~/.gang/notes`）；其中的 `follows/` 记着每次 preview 跟的是哪条附言，也保留 24 小时 |
+| `GANG_NOTES_DIR` | 附言的本地队列，每条一个文件，记着 salt 和提交状态，保留 24 小时（默认 `~/.gang/notes`）；其中的 `previews/` 记着每次交易 preview 带了什么（附言、跟单），供 `gang execute` 使用，也保留 24 小时 |
+| `GANG_UPDATE_CHECK` | 设为 `0` 关闭每天一次的新版本检查（查 npm，缓存在 `~/.gang/update.json`） |
+| `GANG_UPDATE_URL` | 新版本检查查询的地址，默认 `https://registry.npmjs.org/@gangfun/cli/latest`；npmjs 慢或打不开时，可以换成 npm 镜像的 `…/@gangfun/cli/latest` |
 
 ## 版本
 
-`0.6.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.6.1` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gangfun/cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/discover.js

@@ -1,4 +1,6 @@
 /** Discovery for agents: ranked lists + a polling event stream, read from the gang.fun indexer API. */
+import { UA } from './version.js'
+
 export const API = (process.env.GANG_API || 'https://gang.fun/api').replace(/\/+$/, '')
 
 const SOFT_GRAD_BNB = 20
@@ -23,7 +25,7 @@ async function get(path, stop) {
   try {
     let r
     try {
-      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json' } })
+      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json', 'user-agent': UA } })
     } catch (e) {
       if (stop?.aborted) throw e
       throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}. On-chain fallback without volume: \`gang list\``)

package/src/follow.js

@@ -2,13 +2,10 @@
  * Follow trades: a buy that names the note it follows (follow ref in the calldata, see notes.js).
  * gang.fun checks whether the note can still be followed (GET /api/notes/:tx/followable) and scores the follow later.
  */
-import { createHash } from 'node:crypto'
-import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { formatEther } from 'viem'
 import { API } from './discover.js'
 import { fetchError, statusError, why } from './logo.js'
-import { DIR } from './notes.js'
+import { UA } from './version.js'
 
 export const NOTE_TX = /^0x[0-9a-fA-F]{64}$/
 export const MIN_FOLLOW_USD = 1 // gang.fun doesn't count a follow paying less
@@ -17,7 +14,6 @@ export const noteLink = (tx) => `${SITE}/note/${tx.toLowerCase()}`
 
 const NOT_FOUND_RETRIES = 3
 const RETRY_MS = Number(process.env.GANG_FOLLOW_RETRY_MS || 3000) // env only to make tests fast
-const TTL_MS = 24 * 3600_000
 
 export const REASONS = {
   not_found: 'no note with this tx on gang.fun: wrong hash, or the note landed seconds ago and is not indexed yet (try again in a minute)',
@@ -33,7 +29,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 async function getJson(path, timeoutMs = 10_000) {
   let r
   try {
-    r = await fetch(`${API}${path}`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) })
+    r = await fetch(`${API}${path}`, { headers: { accept: 'application/json', 'user-agent': UA }, signal: AbortSignal.timeout(timeoutMs) })
   } catch (e) {
     throw fetchError(`gang API unreachable (${API}): ${why(e)}`, e)
   }
@@ -92,29 +88,3 @@ export function localTime(v) {
   const tz = `UTC${off < 0 ? '-' : '+'}${Math.floor(a / 60)}${a % 60 ? `:${String(a % 60).padStart(2, '0')}` : ''}`
   return `${new Date(ms + off * 60_000).toISOString().slice(0, 16).replace('T', ' ')} ${tz}`
 }
-
-// ---- requestId → followed note, so `gang execute` can print the link. <notes dir>/follows/<sha256(requestId)>.json, kept 24h.
-
-const FDIR = join(DIR, 'follows')
-const pathOf = (requestId) => join(FDIR, `${createHash('sha256').update(String(requestId)).digest('hex').slice(0, 32)}.json`)
-
-/** Best effort: the follow ref is already in the previewed calldata, this only lets `gang execute` print the link. */
-export function rememberFollow(requestId, noteTx) {
-  try {
-    mkdirSync(FDIR, { recursive: true, mode: 0o700 })
-    for (const name of readdirSync(FDIR)) {
-      const p = join(FDIR, name)
-      try { if (Date.now() - statSync(p).mtimeMs > TTL_MS) unlinkSync(p) } catch { /* already gone */ }
-    }
-    const p = pathOf(requestId)
-    writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ noteTx, createdAt: Date.now() }), { mode: 0o600 })
-    renameSync(`${p}.${process.pid}.tmp`, p)
-  } catch { /* execute just won't print the link */ }
-}
-
-export function followFor(requestId) {
-  try {
-    const e = JSON.parse(readFileSync(pathOf(requestId), 'utf8'))
-    return e.createdAt > Date.now() - TTL_MS ? e.noteTx : null
-  } catch { return null }
-}

package/src/index.js

@@ -9,13 +9,17 @@ import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import {
   makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued, followSuffix, readFollowRef,
 } from './notes.js'
-import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime, rememberFollow, followFor } from './follow.js'
+import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
+import { rememberPreview, previewFor } from './previews.js'
+import { UA, checkUpdate } from './version.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
 const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def }
 const flag = (name) => args.includes(`--${name}`)
-const out = (o) => console.log(JSON.stringify(o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
+// set once in main() when npm has a newer CLI; every JSON result then carries it (`gang watch` streams don't)
+let update = null
+const out = (o) => console.log(JSON.stringify(update ? { ...o, update } : o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
 // `gang watch` speaks NDJSON, so its failures are one line too (with event/fatal for stream consumers)
 const fail = (msg, extra = {}) => {
   if (cmd === 'watch') console.log(JSON.stringify({ event: 'error', fatal: true, success: false, error: msg, ...extra }))
@@ -144,7 +148,13 @@ not your own, and buys under $1 don't count. gang.fun is asked first and the buy
 Following a sealed or not-yet-public note is a blind follow; if that note is never revealed, the follow is void.
 
 Logo UI (browser): ${LOGO_UI}
-env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes)`
+
+A buy / sell / create preview without --note says so in agentNote.hint. When npm has a newer CLI, results carry
+update: { current, latest, cmd, skill } (npm is asked at most once a day in the background; GANG_UPDATE_CHECK=0 turns it
+off, GANG_UPDATE_URL points it at an npm mirror).
+
+env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes),
+GANG_UPDATE_CHECK, GANG_UPDATE_URL`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -160,10 +170,25 @@ function summarizePreview(p, extra = {}) {
   }
 }
 
-/** Preview with the note's commitment already in `data`; queue the reveal under the preview's requestId. */
-function summarizeWithNote(p, extra, note, kind) {
+// shown on every buy / sell / create without --note: agents with an old local skill don't know to write one.
+// The CLI can't tell whether the user asked for no note, so the agent decides.
+const NO_NOTE = {
+  attached: false,
+  hint: 'No note attached. Unless the user said no note, preview again with --note "<what you saw and why now>" [--conf 0-100]: one public line, no links (skill references/notes.md).',
+}
+const NO_NOTE_SENT = {
+  attached: false,
+  hint: 'This trade went out without a note. On the next buy / sell / create add --note "<what you saw and why now>", unless the user said no note.',
+}
+
+/**
+ * A trade preview with the note's commitment (and follow ref) already in `data`: queue the reveal under the preview's
+ * requestId, and remember what the preview carried so `gang execute` can report on it.
+ */
+function summarizeWithNote(p, extra, note, kind, follow = null) {
   const s = summarizePreview(p, extra)
-  if (note && s.success) {
+  if (!s.success) return s
+  if (note) {
     queueNote(note, { kind, token: extra.token ?? null, requestId: s.requestId })
     s.agentNote = {
       attached: true, hash: note.hash, text: note.text, conf: note.conf,
@@ -171,16 +196,11 @@ function summarizeWithNote(p, extra, note, kind) {
         ? { revealAfterHours: note.revealAfter / 3600, visibility: `sealed: public ${note.revealAfter / 3600}h after the trade` }
         : { visibility: 'public after execute' }),
     }
+  } else {
+    s.agentNote = NO_NOTE
   }
-  return s
-}
-/** A buy preview; with --follow, remember the followed note under the requestId so `gang execute` can link it. */
-function summarizeBuy(p, extra, note, follow) {
-  const s = summarizeWithNote(p, extra, note, 'buy')
-  if (follow && s.success) {
-    rememberFollow(s.requestId, follow.noteTx)
-    s.follow = { attached: true, ...follow }
-  }
+  if (follow) s.follow = { attached: true, ...follow }
+  rememberPreview(s.requestId, { kind, noted: !!note, ...(follow && { followed: follow.noteTx }) })
   return s
 }
 /** The buy step itself: price the follow (setup steps skip this API call). */
@@ -292,11 +312,11 @@ async function buy(token, bnb, note, followTx, checked = null) {
     const data = withNote(withFollow(calldata.softBuy(token, minOut), follow), note)
     const p = bawPreview({ from: me, to: pad.address, value: parseEther(bnb), data })
     const priced = await pricedFollow(follow, token, pad, q)
-    return out(summarizeBuy(p, {
+    return out(summarizeWithNote(p, {
       step: 'buy', kind: 'soft', token, symbol: info.symbol, pad: pad.id,
       bnbSent: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
       expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut),
-    }, note, priced))
+    }, note, 'buy', priced))
   }
 
   // V2 / U / S: buy(token, quoteIn, minTokensOut) pulls quote ERC-20, so: enough quote → approve → buy
@@ -335,14 +355,19 @@ async function buy(token, bnb, note, followTx, checked = null) {
   const data = withNote(withFollow(calldata.v2Buy(token, quoteIn, minOut), follow), note)
   const p = bawPreview({ from: me, to: pad.address, data })
   const priced = await pricedFollow(follow, token, pad, q)
-  return out(summarizeBuy(p, {
+  return out(summarizeWithNote(p, {
     step: 'buy', kind: 'v2', token, symbol: info.symbol, pad: pad.id, quote: info.quote,
     quoteIn: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
     expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut), quotePath: q.quotePath, deterministic: q.deterministic || false,
-  }, note, priced))
+  }, note, 'buy', priced))
 }
 
+// commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
+const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'token', 'quote', 'buy', 'follow', 'sell',
+  'upload-logo', 'create', 'execute', 'tx'])
+
 async function main() {
+  if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
   switch (cmd) {
     case 'preflight': {
       const issues = []
@@ -420,7 +445,7 @@ async function main() {
         count++
         if (webhook) {
           const p = fetch(webhook, {
-            method: 'POST', headers: { 'content-type': 'application/json' },
+            method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': UA },
             body: JSON.stringify(ev), signal: AbortSignal.timeout(10_000),
           }).then((r) => { if (!r.ok) line({ event: 'error', error: `webhook ${r.status}` }) })
             .catch((e) => line({ event: 'error', error: `webhook: ${e.message}` }))
@@ -566,8 +591,10 @@ async function main() {
       const d = r.data
       const pending = d.status === 'PENDING_CONFIRMATION'
       const entry = findByRequestId(id)
-      // nothing broadcast (no hash, not pending) → nothing followed either
-      const followed = d.txHash || pending ? followFor(id) : null
+      // nothing broadcast (no hash, not pending) → nothing followed, and no trade to remind about
+      const sent = d.txHash || pending
+      const preview = sent ? previewFor(id) : null
+      const followed = preview?.followed
       let note
       if (entry && d.txHash && !pending) note = await revealNote(entry, d.txHash)
       else if (entry && pending) {
@@ -579,6 +606,7 @@ async function main() {
       return out({
         success: true, status: d.status, txHash: d.txHash, orderId: d.orderId, pendingConfirmation: pending,
         ...(note && { note }),
+        ...(!entry && preview && !preview.noted && { agentNote: NO_NOTE_SENT }),
         ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
         next: pending
           ? 'Ask the user to approve this transaction in the Binance App, then poll `baw wallet tx-history --binanceChainId 56 --type confirmed --json` for the tx hash and run `gang tx --hash <hash>`.'

package/src/logo.js

@@ -1,5 +1,6 @@
 import { readFileSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { UA } from './version.js'
 
 const MAX_BYTES = 512 * 1024
 const FETCH_TIMEOUT_MS = 20_000
@@ -40,7 +41,7 @@ async function postLogo(buf, what) {
   try {
     res = await fetch(LOGO_API, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
       body: JSON.stringify({ image }),
     })
     text = await res.text()
@@ -72,7 +73,7 @@ export async function checkGangLogo(uri) {
   let res
   try {
     // the logo route answers HEAD with 405, so GET and drop the body
-    res = await fetch(uri, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    res = await fetch(uri, { headers: { 'user-agent': UA }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
     await res.body?.cancel()
   } catch (e) {
     throw fetchError(`could not check logo ${uri}: ${why(e)}`, e)
@@ -94,7 +95,7 @@ export async function rehostLogoUrl(uri) {
   const msg = `could not download logo ${uri}`
   let res
   try {
-    res = await fetch(uri, { redirect: 'follow', signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: 'image/*' } })
+    res = await fetch(uri, { redirect: 'follow', signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: 'image/*', 'user-agent': UA } })
   } catch (e) {
     throw fetchError(`${msg}: ${why(e)}`, e)
   }

package/src/notes.js

@@ -14,6 +14,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { keccak256, toHex } from 'viem'
 import { API } from './discover.js'
+import { UA } from './version.js'
 
 export const MAGIC = '67616e6701' // "gang" + version 1
 export const MAGIC_V2 = '67616e6702' // "gang" + version 2 (sealed)
@@ -21,6 +22,9 @@ export const FOLLOW_MAGIC = '67616e6703' // "gang" + 03: follow ref (01 / 02 / 0
 const MAX_CP = 280
 const REVEAL_MIN_H = 1, REVEAL_MAX_H = 72
 const LINK = /https?:\/\/|www\.|t\.me\//i
+// a copied command whose placeholder was never filled in (`--note "<your reason>"`): refused by the CLI only, so the
+// server's normalization stays the same
+const PLACEHOLDER = /^<[^<>]{1,40}>$/
 // zero-width + bidi controls, and every C0/C1 control except the whitespace ones (\t \n \v \f \r become a space below)
 const STRIP = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]|(?![\t\n\v\f\r])\p{Cc}/gu
 const TTL_MS = 24 * 3600_000 // the server takes a note (v1 or v2) for 24h after the trade
@@ -62,6 +66,7 @@ export const noteHash = ({ salt, conf, text, revealAfter }) =>
 
 export function makeNote(rawText, rawConf, rawRevealAfter) {
   const text = normalizeNote(rawText)
+  if (PLACEHOLDER.test(text)) throw new Error(`placeholder_note: --note is still the placeholder ${text}; write the actual reason, or drop --note`)
   const conf = parseConf(rawConf)
   const revealAfter = parseRevealAfter(rawRevealAfter)
   const salt = randomBytes(16).toString('hex')
@@ -229,7 +234,7 @@ async function post(entry, tx) {
   try {
     const r = await fetch(`${API}/notes`, {
       method: 'POST', signal: ctl.signal,
-      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
       body: JSON.stringify({
         tx, salt: entry.salt, conf: entry.conf, text: entry.text, ...(entry.revealAfter && { revealAfter: entry.revealAfter }),
       }),

package/src/previews.js

@@ -0,0 +1,34 @@
+/**
+ * What a trade preview carried, by requestId, so `gang execute` can report on it: { kind, noted, followed }.
+ * <notes dir>/previews/<sha256(requestId)>.json, kept 24h. Best effort: the calldata is already fixed by the preview,
+ * a missing record only drops the execute-time follow link / no-note reminder.
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { DIR } from './notes.js'
+
+const PDIR = join(DIR, 'previews')
+const TTL_MS = 24 * 3600_000
+const pathOf = (requestId) => join(PDIR, `${createHash('sha256').update(String(requestId)).digest('hex').slice(0, 32)}.json`)
+
+export function rememberPreview(requestId, data) {
+  try {
+    // first use of previews/: drop the follows/ dir 0.6.0 kept follow links in
+    if (mkdirSync(PDIR, { recursive: true, mode: 0o700 })) rmSync(join(DIR, 'follows'), { recursive: true, force: true })
+    for (const name of readdirSync(PDIR)) {
+      const p = join(PDIR, name)
+      try { if (Date.now() - statSync(p).mtimeMs > TTL_MS) unlinkSync(p) } catch { /* already gone */ }
+    }
+    const p = pathOf(requestId)
+    writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ ...data, createdAt: Date.now() }), { mode: 0o600 })
+    renameSync(`${p}.${process.pid}.tmp`, p)
+  } catch { /* see above */ }
+}
+
+export function previewFor(requestId) {
+  try {
+    const e = JSON.parse(readFileSync(pathOf(requestId), 'utf8'))
+    return e.createdAt > Date.now() - TTL_MS ? e : null
+  } catch { return null }
+}

package/src/version.js

@@ -0,0 +1,85 @@
+/**
+ * The CLI's own version, sent as User-Agent, and a once-a-day check whether npm has a newer one.
+ * Installed agents keep their local copy of the skill, so the CLI output is the only place an old setup learns it's old.
+ * The check never delays a command: results come from a cache that a detached child process refreshes.
+ */
+import { spawn } from 'node:child_process'
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+export const UA = `gang-cli/${VERSION}`
+
+// GANG_UPDATE_URL: an npm mirror's …/@gangfun/cli/latest where registry.npmjs.org is slow or blocked
+const LATEST_URL = process.env.GANG_UPDATE_URL || 'https://registry.npmjs.org/@gangfun/cli/latest'
+const CACHE = join(homedir(), '.gang', 'update.json')
+const DAY_MS = 24 * 3600_000
+const RETRY_MS = 3600_000 // after a failed (or unfinished) refresh, try again in an hour, not on every command
+const FETCH_TIMEOUT_MS = 30_000 // the refresh runs in the background, so a slow registry or proxy is fine
+const SELF = fileURLToPath(import.meta.url)
+
+/** a > b for plain x.y.z versions (pre-release tags are ignored). */
+export function newer(a, b) {
+  const pa = String(a).split(/[.-]/).map(Number), pb = String(b).split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0)
+  }
+  return false
+}
+
+function readCache() {
+  try { return JSON.parse(readFileSync(CACHE, 'utf8')) } catch { return null }
+}
+
+function writeCache(c) {
+  try {
+    mkdirSync(dirname(CACHE), { recursive: true, mode: 0o700 })
+    writeFileSync(`${CACHE}.${process.pid}.tmp`, JSON.stringify(c))
+    renameSync(`${CACHE}.${process.pid}.tmp`, CACHE)
+    return true
+  } catch { return false }
+}
+
+/** Runs in the detached child: ask npm for the latest version and store it. */
+async function refresh() {
+  const prev = readCache()
+  try {
+    const r = await fetch(LATEST_URL, { headers: { accept: 'application/json', 'user-agent': UA }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    if (!r.ok) throw new Error(`HTTP ${r.status}`)
+    const v = (await r.json())?.version
+    if (!/^\d+\.\d+\.\d+/.test(v ?? '')) throw new Error('no version')
+    writeCache({ checkedAt: Date.now(), latest: v })
+  } catch {
+    writeCache({ checkedAt: Date.now(), latest: prev?.latest ?? null, failed: true })
+  }
+}
+
+/**
+ * { current, latest, cmd, skill } when the cached npm version is newer, else null (`skill` refreshes the agent's skill,
+ * which is likely as old as the CLI). Synchronous and never throws.
+ * A stale cache (a day old, or an hour after a failed refresh) starts a background refresh for the next command.
+ * GANG_UPDATE_CHECK=0 turns it off.
+ */
+export function checkUpdate() {
+  if (process.env.GANG_UPDATE_CHECK === '0') return null
+  const c = readCache()
+  const age = Date.now() - (c?.checkedAt || 0)
+  if (!(age >= 0 && age < (c?.latest && !c.failed ? DAY_MS : RETRY_MS))) {
+    // mark it as being checked first, so commands run meanwhile don't each start a refresh
+    if (writeCache({ checkedAt: Date.now(), latest: c?.latest ?? null, failed: true })) {
+      try {
+        spawn(process.execPath, [SELF, 'refresh'], { detached: true, stdio: 'ignore', windowsHide: true }).unref()
+      } catch { /* next hour */ }
+    }
+  }
+  if (!c?.latest || !newer(c.latest, VERSION)) return null
+  return {
+    current: VERSION, latest: c.latest,
+    cmd: 'npm i -g @gangfun/cli@latest',
+    skill: 'npx skills add gangfun/gang-launchpad/skill',
+  }
+}
+
+if (process.argv[1] === SELF && process.argv[2] === 'refresh') refresh()