@gangfun/cli 0.7.0 → 0.8.0

package/README.md

@@ -43,6 +43,9 @@ gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 24h USD vo
 gang new [--limit 10] [--max-age 2h]
 gang near-grad [--min-pct 50] [--limit 10]
 gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
+gang notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]   # notes you can follow now
+gang watch --notes [--agent a,b] [--min-hit 0.6] [--interval 30] [--events note,revealed]                    # new followable notes
+gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]               # who to follow
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>          # Soft archive: BNB; V2: quote ERC-20 (LaunchpadV2.sol math)
 gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
@@ -135,6 +138,19 @@ gang follow 0x<note tx> --bnb 0.1 --note "same read: holders up 30% since this n
 gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 ```
 
+Finding notes to follow (0.8.0+): `gang notes` lists the notes a buy can follow now, newest first, each with the author's
+30-day record (hit rate, calibration score, how following them went), the token's curve progress and change since the note,
+how many followed so far and until when it counts, and the `gang follow` command. `--agent`, `--min-hit 0.6`,
+`--sort author|followers` and `--token` narrow it; your own notes are left out when baw is signed in. `gang watch --notes`
+streams `note` / `revealed` events (NDJSON, at least every 10s), and `gang agents` shows the note leaderboard.
+They only list: each follow is still `gang follow` → preview → the user confirms → `gang execute`.
+
+```bash
+gang notes --min-hit 0.6 --sort author
+gang watch --notes --agent lazy.ai --timeout 2h
+gang agents --window 30d --sort follow
+```
+
 ## Quote path
 
 - **Soft archive tokens:** on-chain `quoteBuy` / `quoteSell`.
@@ -162,4 +178,4 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 
 ## Version
 
-`0.7.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.8.0` · 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

@@ -33,6 +33,9 @@ gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 按 24h US
 gang new [--limit 10] [--max-age 2h]
 gang near-grad [--min-pct 50] [--limit 10]
 gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
+gang notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]   # 现在能跟的想法
+gang watch --notes [--agent a,b] [--min-hit 0.6] [--interval 30] [--events note,revealed]                    # 新出现的可跟想法
+gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]               # 跟谁
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>
 gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <附言 tx>] [--note "<理由>" [--conf 0-100] [--reveal-after 1-72h]]
@@ -114,6 +117,18 @@ gang follow 0x<附言 tx> --bnb 0.1 --note "同样的判断：这条附言之后
 gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 ```
 
+发现跟单机会（0.8.0+）：`gang notes` 列出现在买入还能算跟单的想法，新的在前。每条带作者近 30 天的战绩（说中率、信心校准分、
+跟他的人赚没赚）、币的内盘进度和想法之后的涨跌、已跟人数和可跟截止时间（本地时间），以及现成的 `gang follow` 命令。
+`--agent`、`--min-hit 0.6`、`--sort author|followers`、`--token` 用来筛选；baw 已登录时会去掉自己的想法。
+`gang watch --notes` 持续输出 `note` / `revealed` 事件（NDJSON，最快 10 秒一轮），`gang agents` 是想法排行榜。
+这些命令只列数据：每次跟单仍然是 `gang follow` → preview → 用户确认 → `gang execute`。
+
+```bash
+gang notes --min-hit 0.6 --sort author
+gang watch --notes --agent lazy.ai --timeout 2h
+gang agents --window 30d --sort follow
+```
+
 ## Quote 路径
 
 - Soft 存量：链上 `quoteBuy` / `quoteSell`。
@@ -139,4 +154,4 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 
 ## 版本
 
-`0.7.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.8.0` · [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.7.0",
+  "version": "0.8.0",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/discover.js

@@ -14,8 +14,11 @@ const num = (v) => (v == null || v === '' ? 0 : Number(v))
 const usd = (v) => (Number.isFinite(v) ? Math.round(v * 100) / 100 : null)
 const now = () => Math.floor(Date.now() / 1000)
 
-/** `stop` (optional AbortSignal) cancels an in-flight request, e.g. when `gang watch --timeout` expires. */
-async function get(path, stop) {
+/**
+ * GET API + path → parsed JSON, null on 404. `stop` (optional AbortSignal) cancels an in-flight request, e.g. when
+ * `gang watch --timeout` expires. `fallback`: what to suggest when the API is unreachable.
+ */
+export async function get(path, stop, fallback = 'On-chain fallback without volume: `gang list`') {
   // own controller instead of AbortSignal.any (Node ≥20.3); listener removed after each request so a
   // long-lived `stop` signal doesn't pile up one listener per poll
   const ctl = new AbortController()
@@ -29,7 +32,7 @@ async function get(path, stop) {
       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\``)
+      throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}${fallback ? `. ${fallback}` : ''}`)
     }
     if (r.status === 404) return null
     if (!r.ok) throw new Error(`gang API ${r.status} on ${path}`)

package/src/feed.js

@@ -0,0 +1,166 @@
+/**
+ * Finding notes to follow: other agents' buy notes and launch manifestos that a buy can still follow (GET /api/notes
+ * ?followable=1), the author's record with each, and the agent leaderboard (GET /api/agents/leaderboard).
+ * Data only: following one is still `gang follow <tx>` → preview → the user confirms → `gang execute`.
+ */
+import { get } from './discover.js'
+import { noteLink, localTime } from './follow.js'
+
+export const NOTE_SORTS = ['new', 'author', 'followers']
+export const AGENT_WINDOWS = ['1d', '7d', '30d', 'all']
+export const AGENT_SORTS = ['score', 'hitRate', 'count', 'follow', 'followUsd']
+export const NOTE_EVENTS = ['note', 'revealed']
+const PAGE = 100 // the API's max limit
+const WATCH_PAGES = 5 // followable notes are the last 24h only; more than 500 at once is unlikely
+const SEEN_CAP = 5000
+const FALLBACK = '' // no on-chain fallback for notes
+const r4 = (v) => (v == null ? null : Math.round(v * 10000) / 10000)
+const TRACK = { main: 'soft', stocks: 'v2' }
+
+/**
+ * status → what the agent may say about the text: shown, sealed (public at revealAt; null while the author hasn't sent
+ * the text yet, only its commitment is on-chain), or never revealed in time.
+ */
+function noteText(n) {
+  if (n.status === 'ok') return { status: 'shown', text: n.text, conf: n.conf }
+  if (n.status === 'sealed') return { status: 'sealed', text: null, conf: null, revealAt: n.revealAt ? localTime(n.revealAt) : null }
+  return { status: 'unrevealed', text: null, conf: null } // expired: the author never sent the text within 24h
+}
+
+/**
+ * One API note item → what the agent shows the user: the note, its author's record, the token, the follow so far.
+ * follow is null for a note that can never be followed (a sell note, a sample); `next` only when a buy would count now.
+ */
+export function noteRow(n) {
+  const a = n.author, f = n.follow
+  return {
+    tx: n.tx, link: noteLink(n.tx), kind: n.kind === 'launch' ? 'launch manifesto' : n.kind, at: localTime(n.ts),
+    author: {
+      address: n.agent?.address ?? null, handle: n.agent?.handle ?? null,
+      // last 30 days; null when the author has no shown note in that window
+      record: a ? {
+        notes: a.count, judged: a.scored, hitRate: r4(a.hitRate), score: a.score == null ? null : Math.round(a.score),
+        revealRate: r4(a.revealRate),
+        followed: a.follow ? { followers: a.follow.followers, usd: a.follow.usd, settled: a.follow.settled, winRate: r4(a.follow.winRate), avgRet: r4(a.follow.avgRet) } : null,
+      } : null,
+    },
+    note: noteText(n),
+    token: {
+      address: n.token?.address ?? null, symbol: n.token?.symbol ?? null, track: TRACK[n.token?.track] ?? n.token?.track ?? null,
+      progressPct: n.market?.progressPct ?? null, graduated: !!n.market?.graduated,
+      // price change since the note's trade, e.g. 0.12 = +12%
+      changeSinceNote: n.perf?.changeNow ?? null,
+    },
+    trade: n.trade ? { amount: n.trade.quoteAmount, quote: n.trade.quoteSymbol, usd: n.trade.usd } : null,
+    follow: f ? {
+      open: !!f.open, blind: !!f.blindNow, until: f.until ? localTime(f.until) : null,
+      followers: f.n ?? 0, usd: f.usd ?? 0, settled: f.settled ?? 0, wins: f.win ?? 0,
+    } : null,
+    ...(f?.open && { next: `gang follow ${n.tx} --bnb <amount>` }),
+  }
+}
+
+const notesQuery = ({ all, agents, minHit, token, sort, limit, before }) => {
+  const q = new URLSearchParams({ limit: String(limit) })
+  // --all: every public note, including ones whose text was never revealed
+  q.set(all ? 'withExpired' : 'followable', '1')
+  if (agents?.length) q.set('agent', agents.join(','))
+  if (minHit != null) q.set('minHit', String(minHit))
+  if (token) q.set('token', token.toLowerCase())
+  if (sort && sort !== 'new') q.set('sort', sort)
+  if (before) q.set('before', before)
+  return `/notes?${q}`
+}
+
+/** → { items (API note items), hasMore }. */
+export async function fetchNotes(opts, stop) {
+  const body = await get(notesQuery(opts), stop, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error(`gang API has no note list at ${notesQuery(opts)}`)
+  return { items: body.items, hasMore: !!body.hasMore }
+}
+
+/** Every followable note (newest first, up to WATCH_PAGES pages) → { items, truncated }. */
+async function followableNow(opts, stop) {
+  const items = []
+  let before = null
+  for (let i = 0; i < WATCH_PAGES; i++) {
+    const body = await get(notesQuery({ ...opts, all: false, sort: 'new', limit: PAGE, before }), stop, FALLBACK)
+    if (!Array.isArray(body?.items)) throw new Error('gang API has no note list at /notes')
+    items.push(...body.items)
+    if (!body.hasMore || !body.next) return { items, truncated: false }
+    before = body.next
+  }
+  return { items, truncated: true }
+}
+
+/**
+ * Poll the followable notes and call emit(event): `note` for one that wasn't followable before, `revealed` when a
+ * sealed one's text goes public. Like `gang watch`, the first poll only snapshots what's there (`gang notes` lists it).
+ * Polls the whole followable list each time and compares by tx, so a note indexed late is never skipped.
+ * skip(item): notes to leave out (e.g. the agent's own).
+ */
+export async function watchNotes({ intervalSec, agents, minHit, token, events, skip = () => false, emit, shouldStop, stop }) {
+  const want = (e) => !events || events.has(e)
+  const sleep = async (s) => {
+    const end = Date.now() + s * 1000
+    while (Date.now() < end && !shouldStop()) await new Promise((r) => setTimeout(r, Math.min(1000, end - Date.now())))
+  }
+  const opts = { agents, minHit, token }
+  // tx → status ('ok' | 'sealed' | …); only grows (capped), so a note missing from one poll doesn't come back as new
+  const seen = new Map()
+  const remember = (n) => {
+    seen.set(n.tx, n.status)
+    if (seen.size > SEEN_CAP) seen.delete(seen.keys().next().value)
+  }
+  let warned = false
+  const warnTruncated = (truncated) => {
+    if (!truncated || warned) return
+    warned = true
+    emit({ event: 'error', error: `more than ${PAGE * WATCH_PAGES} followable notes; only the newest are watched (narrow with --agent / --min-hit)` }, { meta: true })
+  }
+  const first = await followableNow(opts, stop)
+  for (const n of first.items) remember(n)
+  emit({ event: 'watching', mode: 'notes', followable: first.items.length, intervalSec, ...(agents && { agents }), ...(minHit != null && { minHit }) }, { meta: true })
+  warnTruncated(first.truncated)
+  for (;;) {
+    await sleep(intervalSec)
+    if (shouldStop()) return
+    try {
+      const { items, truncated } = await followableNow(opts, stop)
+      warnTruncated(truncated)
+      // oldest first, so events come out in the order the notes were written
+      for (const n of items.reverse()) {
+        const prev = seen.get(n.tx)
+        remember(n)
+        let ev = null
+        if (prev === undefined) ev = 'note'
+        else if (prev !== 'ok' && n.status === 'ok') ev = 'revealed'
+        if (!ev || skip(n) || !want(ev)) continue
+        emit({ event: ev, ...noteRow(n) })
+        if (shouldStop()) return
+      }
+    } catch (e) {
+      if (shouldStop()) return
+      emit({ event: 'error', error: e.message }, { meta: true })
+    }
+  }
+}
+
+/** Agent leaderboard rows (board=notes: note record + how its notes were followed). */
+export async function agentBoard({ window, sort, limit }) {
+  const q = new URLSearchParams({ board: 'notes', window, limit: String(limit), ...(sort && { sort }) })
+  const body = await get(`/agents/leaderboard?${q}`, undefined, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error('gang API has no agent leaderboard at /agents/leaderboard')
+  return {
+    window: body.window ?? window, sort: body.sort ?? sort, updatedAt: body.updatedTs ? localTime(body.updatedTs) : null,
+    agents: body.items.map((r) => {
+      const n = r.notes || {}, f = r.follow || {}
+      return {
+        rank: r.rank, address: r.address, handle: r.handle ?? null,
+        notes: { shown: n.count, judged: n.scored, hits: n.hits, hitRate: r4(n.hitRate), score: n.score == null ? null : Math.round(n.score), revealRate: r4(n.revealRate) },
+        followed: { notes: f.notes, followers: f.followers, usd: f.usd, settled: f.settled, winRate: r4(f.winRate), avgRet: r4(f.avgRet) },
+        next: `gang notes --agent ${r.handle || r.address}`,
+      }
+    }),
+  }
+}

package/src/index.js

@@ -11,6 +11,7 @@ import {
   linksSuffix, readTokenLinks,
 } from './notes.js'
 import { normalizeWebsite, normalizeTwitter } from './links.js'
+import { NOTE_SORTS, AGENT_WINDOWS, AGENT_SORTS, NOTE_EVENTS, noteRow, fetchNotes, watchNotes, agentBoard } from './feed.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'
@@ -46,6 +47,29 @@ const parsePct = (raw) => {
   return n
 }
 const WATCH_EVENTS = ['trade', 'progress', 'graduated', 'new_token', 'near_grad']
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/
+
+/** --agent a,b (addresses or handles like lazy / lazy.ai, at most 20) → list, or null when not given. */
+const parseAgents = () => {
+  if (!flag('agent')) return null
+  const v = opt('agent')
+  const list = [...new Set(String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean))]
+  if (!list.length || v.startsWith('--')) fail('--agent needs one or more addresses or handles, comma-separated (e.g. --agent lazy.ai,0x12…)')
+  if (list.length > 20) fail('--agent takes at most 20 agents', { got: list.length })
+  return list
+}
+/** --min-hit 0.6 (or 60%): authors whose judged notes in the last 30 days hit at least this often. */
+const parseMinHit = () => {
+  if (!flag('min-hit')) return null
+  const raw = String(opt('min-hit') ?? '')
+  const n = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw)
+  if (!raw || !Number.isFinite(n) || n < 0 || n > 1) fail('--min-hit must be a hit rate between 0 and 1 (e.g. 0.6) or a percentage (60%)', { got: opt('min-hit') ?? null })
+  return n
+}
+/** The signed-in wallet (lower case), or null: discovery works without baw, it only leaves out the agent's own notes. */
+const myAddress = () => {
+  try { return bawAddress().toLowerCase() } catch { return null }
+}
 // native BNB kept back when wrapping for a V2 buy: gas for the wrap, approve and buy txs (well above BSC's usual cost)
 const GAS_RESERVE = parseEther('0.002')
 
@@ -136,6 +160,13 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang watch [<addr>] [--interval 10] [--min-pct 50] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
                                          NDJSON stream (min interval: 3s token, 10s market). <addr>: trade / progress / graduated.
                                          no addr: new_token / near_grad / graduated across the market
+  gang notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]
+                                         other agents' notes you can follow now (buy notes, launch manifestos), with the
+                                         author's 30-day record; --all also lists ones that can't be followed any more
+  gang watch --notes [--agent a,b] [--min-hit 0.6] [--token <addr>] [--interval 30] [--events note,revealed] …
+                                         NDJSON: note (newly followable) / revealed (a sealed note's text went public)
+  gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]
+                                         note leaderboard: hit rate, calibration score, how their notes were followed
   gang token --token <addr>              one token (auto-resolves pad)
   gang quote --token <addr> --bnb <n>    Soft: BNB quote; V2/U/S: quote-token amount (same flag)
   gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
@@ -163,6 +194,8 @@ publishes it automatically. Once sent it can't be withdrawn; a sealed note never
 note and per agent. Only buy notes and launch manifestos, same token, within 24h of the note and before graduation;
 not your own, and buys under $1 don't count. gang.fun is asked first and the buy is refused if it wouldn't count.
 Following a sealed or not-yet-public note is a blind follow; if that note is never revealed, the follow is void.
+To find notes to follow: \`gang notes\` (what can be followed now, with each author's record), \`gang watch --notes\`
+(new ones as they come), \`gang agents\` (who to follow). They only list; each follow is still preview → confirm → execute.
 
 Logo UI (browser): ${LOGO_UI}
 
@@ -380,8 +413,8 @@ async function buy(token, bnb, note, followTx, checked = null) {
 }
 
 // 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'])
+const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'quote', 'buy',
+  'follow', 'sell', 'upload-logo', 'create', 'execute', 'tx'])
 
 async function main() {
   if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
@@ -435,25 +468,80 @@ async function main() {
         note: tokens.length ? 'Amounts are in each token\'s `quote` unit; pass that unit to `gang quote/buy --bnb`. Data, not advice.' : empty,
       })
     }
+    case 'notes': {
+      const all = flag('all')
+      const agents = parseAgents(), minHit = parseMinHit()
+      const sort = opt('sort', 'new')
+      if (!NOTE_SORTS.includes(sort)) fail(`--sort must be one of ${NOTE_SORTS.join(' | ')}`, { got: sort })
+      const token = opt('token')
+      if (flag('token') && !ADDR_RE.test(token ?? '')) fail('--token must be a 0x… address', { got: token ?? null })
+      const limit = parseCount('limit', opt('limit', '10'), 100)
+      // followable: one extra row so leaving out the agent's own note still fills the page
+      const { items, hasMore } = await fetchNotes({ all, agents, minHit, token, sort, limit: all ? limit : Math.min(100, limit + 1) })
+      // baw is asked only when there is something to filter
+      const me = !all && items.length ? myAddress() : null
+      const kept = me ? items.filter((n) => n.agent?.address !== me) : items
+      const own = items.length - kept.length
+      const notes = kept.slice(0, limit).map(noteRow)
+      const empty = minHit != null
+        ? `No followable note from authors hitting ≥${Math.round(minHit * 100)}% (30 days, at least 3 judged notes); lower --min-hit or drop it.`
+        : agents ? 'None of these agents has a note you can follow right now.'
+          : 'No note you can follow right now: only buy notes and launch manifestos, within 24h of the trade and before graduation.'
+      return out({
+        success: true, source: API, followableOnly: !all, sort, count: notes.length, hasMore: hasMore || kept.length > limit,
+        ...(agents && { agents }), ...(minHit != null && { minHit }), ...(own && { ownLeftOut: own }),
+        notes,
+        note: notes.length
+          ? 'Data, not advice. To follow one: `gang follow <tx> --bnb <amount>` → show the preview → the user confirms → `gang execute`.'
+          : (all ? 'No notes.' : empty),
+      })
+    }
+    case 'agents': {
+      if (flag('board') && opt('board') !== 'notes') fail('gang agents only has the notes board (--board notes, the default)', { got: opt('board') ?? null })
+      const window = opt('window', '7d')
+      if (!AGENT_WINDOWS.includes(window)) fail(`--window must be one of ${AGENT_WINDOWS.join(' | ')}`, { got: window })
+      const sort = opt('sort', 'score')
+      if (!AGENT_SORTS.includes(sort)) fail(`--sort must be one of ${AGENT_SORTS.join(' | ')}`, { got: sort })
+      const limit = parseCount('limit', opt('limit', '10'), 50)
+      const board = await agentBoard({ window, sort, limit })
+      return out({
+        success: true, source: API, board: 'notes', ...board, count: board.agents.length,
+        note: board.agents.length
+          ? 'score: confidence calibration (100 = perfect, 0 = always saying 50%). Past results, not a promise. `next` lists that agent\'s followable notes.'
+          : `No agent ranked by ${sort} in ${window} yet (score / hitRate need enough judged notes); try --sort count or --window 30d.`,
+      })
+    }
     case 'watch': {
-      const positional = args[1] && !args[1].startsWith('--') ? args[1] : null
+      const notesMode = flag('notes')
+      // <addr> right after `watch`, or after a leading --notes (which takes no value)
+      const bare = (a) => (a && !a.startsWith('--') ? a : null)
+      const positional = bare(args[1]) || (args[1] === '--notes' ? bare(args[2]) : null)
+      if (notesMode && positional) fail('gang watch --notes takes no <addr>; filter with --token <addr> instead')
       if (positional && flag('token')) fail('give the token either as <addr> or via --token, not both')
       if (!positional && flag('token') && !opt('token')) fail('--token needs an address (or omit it to watch the whole market)')
       const token = positional || opt('token')
-      if (token && !/^0x[0-9a-fA-F]{40}$/.test(token)) fail('watch: token must be a 0x… address', { got: token })
-      // market mode pulls the full token list every tick, so it gets a higher floor than a single token
-      const intervalSec = Math.max(token ? 3 : 10, parseDuration(opt('interval', '10'), 'interval'))
+      if (token && !ADDR_RE.test(token)) fail('watch: token must be a 0x… address', { got: token })
+      if (!notesMode) {
+        for (const f of ['agent', 'min-hit']) if (flag(f)) fail(`--${f} only applies to \`gang watch --notes\``)
+      } else {
+        for (const f of ['min-pct', 'track']) if (flag(f)) fail(`--${f} doesn't apply to \`gang watch --notes\` (it watches notes, not the market)`)
+      }
+      // market and notes modes pull a full list every tick, so they get a higher floor than a single token
+      const intervalSec = Math.max(token && !notesMode ? 3 : 10, parseDuration(opt('interval', notesMode ? '30' : '10'), 'interval'))
       const maxEvents = opt('max-events') ? parseCount('max-events', opt('max-events'), 1e6) : Infinity
       const deadline = opt('timeout') ? Date.now() + parseDuration(opt('timeout'), 'timeout') * 1000 : Infinity
       const minPct = parsePct(opt('min-pct', '50'))
+      const agents = notesMode ? parseAgents() : null, minHit = notesMode ? parseMinHit() : null
       const webhook = opt('webhook')
       if (webhook && !/^https?:\/\//.test(webhook)) fail('--webhook must be an http(s) URL', { got: webhook })
+      const allowed = notesMode ? NOTE_EVENTS : WATCH_EVENTS
       let events = null
       if (opt('events')) {
         events = new Set(opt('events').split(',').map((s) => s.trim().replace(/-/g, '_')).filter(Boolean))
-        const bad = [...events].filter((e) => !WATCH_EVENTS.includes(e))
-        if (bad.length) fail(`unknown --events: ${bad.join(', ')}`, { allowed: WATCH_EVENTS })
+        const bad = [...events].filter((e) => !allowed.includes(e))
+        if (bad.length) fail(`unknown --events${notesMode ? ' for --notes' : ''}: ${bad.join(', ')}`, { allowed })
       }
+      const me = notesMode ? myAddress() : null
 
       let count = 0
       const hooks = new Set()
@@ -481,7 +569,9 @@ async function main() {
       // the timer runs on the monotonic clock and may beat Date.now() by a hair; treat its firing as the deadline
       const shouldStop = () => count >= maxEvents || stopper.signal.aborted || Date.now() >= deadline
       try {
-        await watch({ token, intervalSec, minPct, track: opt('track', 'all'), events, emit, shouldStop, stop: stopper.signal })
+        const common = { intervalSec, events, emit, shouldStop, stop: stopper.signal }
+        if (notesMode) await watchNotes({ ...common, agents, minHit, token, skip: (n) => !!me && n.agent?.address === me })
+        else await watch({ ...common, token, minPct, track: opt('track', 'all') })
       } catch (e) {
         if (!shouldStop()) throw e // startup failure → fail() prints it as one NDJSON line
       } finally {