NodeNanny

# AGENTS.md

This file is for AI coding assistants working on this repository. It is committed to
the repo and meant to be read on first clone, independent of any chat session or
handoff document. It states facts and invariants, not narrative history — for the
full story behind any decision below, check `git log` and commit messages, not this
file.

## Project identity

NodeNanny is a caretaker tool for **one non-technical person self-hosting one proxy
node, alone**. It does not deploy the node itself (existing one-click installer
scripts do that) — it takes over after deployment: uptime monitoring, automatic
restart, failure emails, optional advisory-only AI failure diagnosis (using the
user's own API key), and a status panel in 5 languages (zh/en/ja/de/ru).

It is explicitly **not** a multi-user/multi-node management panel and does not
compete with Marzban/3X-UI/Remnawave. Multi-node/fleet management has been proposed
and explicitly rejected by the maintainer before — do not re-propose it without the
maintainer explicitly reopening the topic.

The maintainer is non-technical, manages the server alone, and communicates in
Chinese. If you are drafting anything the maintainer will read directly (chat
replies, commit messages meant for them, doc updates aimed at them), use Chinese.
This file itself is English because it's aimed at AI assistants, not the maintainer.

## Working model — read this before touching anything

The AI assistant in a chat session has **no SSH access to any server and no git push
credentials**. Every server-side command and every git command must be run by the
maintainer himself, one command at a time, in a terminal he explicitly opens. If you
are an AI assistant with actual tool access to this repo (e.g. an agentic coding
tool with shell access), you may still lack the credentials to push or deploy —
check what you actually have access to before assuming you can complete the full
workflow end to end.

Standard workflow for any code change:
1. Edit in a sandbox, cloned fresh from GitHub (`https://github.com/yibentq/nodenanny`,
   public, AGPL-3.0) — never trust an uploaded zip's `.git` state as current without
   checking `git log` / `git status` yourself first.
2. Hand changed files to the maintainer.
3. Maintainer copies them into the local working copy, runs `git add` / `git commit`
   / `git push` himself.
4. Maintainer `scp`s changed files to the experimental server and restarts the
   relevant PM2 process(es) himself.

Do not assume any file is "live" anywhere (local working copy, GitHub, or the
server) until this full chain is confirmed. These three locations can and have
drifted out of sync before.

## Servers

- **Production**: `186.241.91.103` — legacy, long untouched, `pool.enabled=false`.
  **Do not touch.**
- **Experimental**: `186.244.208.32` — the live, working deployment.
  `ssh [email protected]:22`. Code lives at `/root/nodenanny`, deployed via `scp`
  — **it is not a git checkout on the server**. PM2 process names:
  `nodenanny-monitor`, `nodenanny-panel`, `nodenanny-pool`. **The maintainer's actual
  day-to-day access is `https://186.244.208.32:49769` (self-signed cert + HTTP Basic
  Auth), not an SSH tunnel** — see `deploy/experimental-server-access-notes.md` for
  the full access setup (a second port, `35319`, exposes only the subscription path,
  no auth). That file also documents that the panel-login / terminal-unlock /
  port-`49769` Basic-Auth passwords are **deliberately identical** — a maintainer
  choice on a zero-budget solo project, not an oversight; don't "fix" it unprompted.
  None of these credentials are ever written into this file or any git-tracked file.

## File → PM2 process map

Grep `require()` chains before assuming which process(es) load a file you're
changing — don't guess from the list below if it's ambiguous.

- `core/pool.js`, `core/proxy-parse.js`, `core/repo-fetch.js`,
  `core/telegram-fetch.js`, `core/source-list-sync.js`, `core/pool-checker.js`,
  `core/source-trust.js` → restart `nodenanny-pool`.
- `core/panel-server.js`, `public/*.html` → restart `nodenanny-panel`.
- `core/checker.js`, `core/notify.js`, `core/ai-provider.js` → required by **both**
  `nodenanny-monitor` and `nodenanny-panel`.

## Config

`config/config.json` is gitignored (it holds secrets — SMTP credentials, API keys,
panel password). `config/config.example.json` is the committed template. **Never**
write real secrets into this file, into a commit, or into any handoff/chat document.

## Running the test suite in a sandbox

`node-pty` (needed for the terminal feature) is a native module and typically fails
to compile in a throwaway sandbox with no matching prebuilt binary. If you need to
run `npm install` in a sandbox to execute the test suite, temporarily remove
`node-pty` from `package.json`'s dependencies first, run the tests, then restore it
and confirm a clean `git diff` on `package.json`/`package-lock.json` before handing
anything back — don't let a sandbox workaround leak into a real commit.

## Invariants — do not break these without the maintainer's explicit sign-off

- `manualSources` entries with `"fixed": true` are exempt from the
  trial→trusted→blacklisted state machine (`resolveManualSourceTrust()` in
  `core/pool.js`). No sync/merge mechanism may ever overwrite or strip `fixed: true`
  off a source it didn't create.
- `core/source-list-sync.js` tracks which ids it created in
  `data/source-list-sync-state.json` (a ledger of managed ids). Any local id not on
  that ledger is always treated as a conflict and skipped, never overwritten.
- Auto-fetched sources (Telegram, GitHub discovery) do **not** get `fixed: true` —
  they earn trust through the normal state machine like any other source. This was
  an explicit maintainer decision: a human picking the source does not pre-vet its
  content.
- **sing-box** is the verification backend for `core/pool-checker.js`. It has no SSR
  outbound support. Do not add an SSR parser to `core/proxy-parse.js` unless the
  maintainer decides to switch checking engines — an SSR parser would produce
  output nothing downstream can actually test.
- `core/proxy-parse.js` currently supports: `vless`, `vmess`, `ss`, `trojan`,
  `hysteria2`/`hy2`, `hysteria` (v1), `tuic`, `anytls`, `socks5`, `http`, `https`.
  `ssr` and `shadowtls` are deliberately excluded — see in-file comments for why
  before attempting to add either.
- `core/telegram-fetch.js`'s `document_attachment` path is confirmed
  non-functional: Telegram's public, login-free preview page (`t.me/s/<channel>`)
  exposes only a message permalink for file attachments, not a real download URL.
  This was live-verified against a real channel, not assumed. Do not attempt
  to fix `document_attachment` without the maintainer explicitly approving new
  credentials (a bot added as channel admin by the channel owner, or a full MTProto
  user login) — both are out of scope until then, and for a third-party channel the
  maintainer doesn't own, bot-admin access usually isn't obtainable at all.
- `message_text_link` (plain-text links) and `message_text_code_link` (links inside
  a `<code>`/`<pre>` block) are both live-verified working sub-paths. Code/pre-block
  links take priority over plain-text `<a href>` links across the whole scanned
  message window — real channels in this genre consistently paste the actual
  subscription link in a code block for easy mobile copy/paste, while plain-text
  links in the same messages are more often unrelated promotional content. `t.me`/
  `telegram.me` links and any candidate URL containing `@` (userinfo@host — this
  matches individual raw node URIs like `vless://uuid@host:port` sometimes pasted
  with an `https://` typo prefix, not real subscription API URLs) are excluded as
  candidates.
- `telegramFetch.extractRawNodeLinks()` separately harvests raw node URIs
  (`vless/vmess/ss/trojan/hysteria2/hy2/hysteria/tuic/anytls/socks5://`, no `ssr`)
  pasted directly in a channel's message text — this is independent of whether a
  subscription link was found on the same fetch. `fetchLatestFileUrl()` returns
  `rawHtml` on every path (success or failure) precisely so callers can harvest
  these without a second network request.
- **Trust identity for Telegram-resolved subscription links is domain-based, not
  channel-based.** `core/pool.js`'s `fetchFromManualSource()` uses a `trustSourceId`
  (`manual-tg-sub:<hostname>`) that is separate from the display `sourceId`
  (`manual:<channel-id>`, still used for panel roster/star-map/pool-events display
  and for `passedNodes[].sourceId`). This exists because these subscription links
  carry per-request/per-day rotating tokens — using the full URL as trust identity
  would mean trial progress resets constantly and 7-round promotion could never
  complete. **Anomaly detection is computed and logged as normal but does *not* feed
  into blacklisting for `manual-tg-sub:*` identities** (`anomalyForTrust` is forced
  `false` for this namespace only) — a legitimate multi-region subscription service
  showing the same account identity on multiple servers is expected behavior, not
  fraud. Non-Telegram manual sources (`trustSourceId` still `manual:<id>`) are
  unaffected — anomaly detection blacklists them normally. **This anomaly-suppression
  default was an AI judgment call during the redesign, not something the maintainer
  has explicitly signed off on** — he was asked and said he doesn't understand the
  mechanism well enough to have an opinion yet, so treat it as "current behavior,
  revisit if it ever causes a real problem or he raises it," not as settled product
  policy.
- Raw nodes harvested across *all* Telegram-channel manual sources in one refresh
  round are pooled together into a single shared source, `telegram-raw-pool`
  (constant `TELEGRAM_RAW_POOL_SOURCE_ID` in `core/pool.js`) — deliberately **not**
  merged into `aggregator-default` (confirmed useless, consistently 0 passes) and
  deliberately **not** given a fixed/configurable weight override — it goes through
  the normal trial→trusted→blacklisted state machine like any other non-fixed
  source. Anomaly detection is *not* suppressed for this pool (unlike the
  `manual-tg-sub:*` case above) — raw nodes pasted by different channels colliding
  on identity doesn't have the same "legitimate multi-region service" justification.
- `parseSubscriptionContent()` (`core/repo-fetch.js`) reports `format: 'unrecognized'`
  whenever zero usable links come out the other end — **including** when the input
  actually is valid Clash YAML but every proxy entry uses an unsupported protocol
  (e.g. all-SSR). Seeing `unrecognized` in logs for a Telegram/GitHub source does not
  by itself mean the parser failed to recognize the format; check `yamlTotal` vs
  `yamlConverted` (when present) or inspect the raw content before assuming a parser
  bug.
- `core/clash-yaml.js`'s `extractProxiesBlockLines()` supports **both** YAML list
  styles for the `proxies:` block — the conventional indented-dash style
  (`proxies:\n  - name: ...`) and the equally-valid flush-left style
  (`proxies:\n- name: ...`, list items at the *same* indentation as the key). It
  derives the list's actual indentation from the first item found rather than
  assuming a fixed relationship to the `proxies:` key's own indentation. If this
  ever needs touching again, don't reintroduce the fixed-relationship assumption —
  it silently produces an empty block (and therefore `format: 'unrecognized'`) for
  any flush-left file, which is common among real channels tested (clashv8,
  wxdy666).
- `core/repo-fetch.js`'s `fetchText()` has a fallback path for
  `UND_ERR_HEADERS_OVERFLOW` (Node's default header-size ceiling, hit when a 3xx
  redirect's `Location` header is itself huge — some subscription services encode
  the entire node list into the redirect target URL rather than a normal response
  body). On that specific error it retries via Node's built-in `http`/`https` module
  with a raised `maxHeaderSize`, manually following redirects (Node's built-in
  modules don't auto-follow them the way `fetch()`/`curl -L` do). This is a narrow,
  specific fallback for one known failure mode — don't broaden it into a blanket
  catch-and-retry for other error types.
- **Panel's online terminal requires a WebSocket-upgrade-aware reverse proxy.**
  `scripts/setup-reverse-proxy.sh`'s generated Nginx config must include
  `proxy_http_version 1.1;`, `proxy_set_header Upgrade $http_upgrade;`, and
  `proxy_set_header Connection "upgrade";` on the panel's `location /` block —
  without these, the terminal connects (auth succeeds) and then closes immediately,
  because Nginx never actually upgrades the connection to a WebSocket. If a
  maintainer reports "terminal unlocks then disconnects instantly," check the
  reverse-proxy config for these three lines before suspecting `core/terminal.js`
  itself.
- `public/wiki.html`'s internal-link resolver must strip the numeric order-prefix
  (e.g. `04-` in `04-compliance-and-risk`) from a cross-category relative link's
  category segment before matching — the backend's `categoryId` never includes this
  prefix (see `stripOrderPrefix` in `core/wiki-manager.js`). Same-category links
  (`./slug`) don't hit this path and worked before the fix; only cross-category
  links (`../<numbered-category>/slug`) were affected.
- `core/source-list-sync.js` (config field `sourceListSync.owner/repo/ref/path`,
  panel section "节点来源列表同步") deliberately strips any `fixed` field from
  remote-supplied entries regardless of what the remote JSON contains — every
  source it merges in enters the normal trial state machine, mirroring the
  "auto-fetched sources don't get `fixed: true`" invariant above. It is now offered
  in `install.sh`'s interactive content-sync bundle alongside `kbSync`/`wikiSync`
  (installed configs get all three pointed at the maintainer's own repo by default);
  fresh installs are covered, but this does **not** retroactively populate
  `sourceListSync` on an already-running server's `config.json` — that still needs a
  manual edit + `nodenanny-panel` restart, same as `kbSync`/`wikiSync`'s equivalent
  gap.
- `panel-server.js`'s `config` object (including `sourceListSync`/`kbSync`/
  `wikiSync`/general settings) is loaded **once** at process startup into a closure
  variable, **not** re-read per request. Any `config.json` edit intended to affect
  panel behavior requires an `nodenanny-panel` restart to take effect — this is not
  specific to `sourceListSync`, it's how the whole file is loaded.
- Terminal-password setup (`ask_secret` in `scripts/i18n.sh`, used by `install.sh`)
  now asks twice and retry-loops on mismatch before accepting — a typo during setup
  used to go completely undetected until the maintainer tried to actually use the
  terminal later and got locked out without knowing why.
- `install.sh` supports non-interactive mode (`NN_NONINTERACTIVE=true`, or
  automatically when stdin isn't a tty) plus per-field `NN_*` environment variables
  (see `scripts/i18n.sh`'s `ask`/`ask_secret`/`ask_yn` helpers). `NN_PANEL_PASSWORD`
  is mandatory in non-interactive mode — the script exits non-zero if it's unset or
  empty. This is intentional; do not relax it.

- Manual backup-pool switch (`state.poolManualOverride` in `core/store.js`, endpoint
  `POST /api/pool/manual-toggle` in `core/panel-server.js`) is a human-triggered
  override, not automatic failover — when active, `core/checker.js`'s normal
  pool→self auto-revert-on-recovery is suppressed until the maintainer manually
  toggles back. Blocks (400 `pool_empty`) rather than allowing an empty-pool switch.
  This is a deliberately separate mechanism from the trial/trusted/blacklisted
  source-trust state machine above — don't conflate the two.
- `install.sh`'s AI-provider setup supports a third option, `openai-compatible`
  (any OpenAI-compatible third-party endpoint — the maintainer's real diagnosis
  provider, Zhipu/GLM, is configured this way: `baseUrl: "open.bigmodel.cn"`,
  `apiPath: "/api/paas/v4/chat/completions"` — note this is **not** the
  OpenAI-standard default path, don't assume a third-party provider uses
  `/v1/chat/completions` without checking its docs). Unlike `anthropic`/`openai`
  (which have runtime fallback model defaults in `core/ai-provider.js`,
  `claude-sonnet-4-6`/`gpt-4o-mini`), `openai-compatible` has no universal default
  model and `diagnoseWithOpenAICompatible()` throws if `model` is empty — the
  installer enforces a non-empty answer for this path specifically (interactive
  mode retry-loops; non-interactive mode warns loudly to stderr rather than hanging).

## Permanently out of scope

Do not implement or re-propose the following without the maintainer explicitly
reopening the topic (a past AI proposing multi-node support once, and it being
rejected, is exactly the kind of history this file exists to prevent repeating):
AI node panels, node-pool aggregation as a headline feature, multi-region/
multi-cloud failover, multiple payment channels, a self-trained AI model, code
obfuscation, paid tiers, ads, growth hacking, multi-node/fleet management.

"Non-GitHub traffic-pool sources" was previously excluded but this specific
exclusion **was lifted** by the maintainer to allow Telegram channels as backup-pool
sources — that reopening already happened; don't ask again on that specific point.
All other exclusions above remain in force.

## Before you start any session

1. Don't trust a document's or an uploaded zip's claims about current state at face
   value — run `git log --oneline -5` and `git status` yourself if you have file
   access, and reconcile any conflicting claims against that ground truth.
2. Check the current open-items list (kept in the chat-pasted handoff document the
   maintainer provides each session, not duplicated here) before starting new work.
3. If scope for a requested task is ambiguous (e.g. "update the README" with no
   further detail), ask the maintainer what's in scope before writing — don't guess
   at scope for anything that will be presented back to end users.