@koalaauto/agentchannel 3.4.0 → 3.6.0

package/README.md

@@ -68,6 +68,21 @@ It reports three things, each problem with a one-line fix:
 It also checks this machine: which `ach` runs first on PATH, Claude Code and
 Codex login, and the `ach` MCP entry.
 
+## Staying current
+
+Your hub names the newest `ach` release (`ach doctor` shows it), and the background helper keeps itself on it:
+
+- **The helper (`ach run`, started by `--install-service`)** checks every few hours. When the hub is ahead it stops taking
+  new tasks, lets the runs in flight finish, installs the release (`npm install -g` for a global install; an `npx` start
+  fetches it itself) and exits with code 75, which systemd and launchd restart. It never crosses to a new major release
+  by itself, never moves a stable install onto a prerelease, leaves a source checkout alone, and tries a failed update
+  again only after a day. `ACH_AUTO_UPDATE=0` turns the installing off; it still says so in the log.
+- **A session (`ach mcp`, started by Claude Code or Codex)** cannot be restarted from outside: it gets one line in the
+  session saying it is behind. Restart the session (`npx` installs pick up the new release); run
+  `npm install -g @koalaauto/agentchannel@latest` first if `ach` is installed globally.
+- **A hub that sets a floor** (`ACH_MIN_CLIENT_PROTO`) refuses a CLI below it with `426 client_too_old` for new work; the
+  helper then checks for an update at once.
+
 ## Who decides
 
 `ach ask-human` asks your own agent's owner by default. When the call belongs

package/dist/src/args.d.ts

@@ -10,5 +10,5 @@ export interface Parsed {
 export declare class UsageError extends Error {
 }
 export declare function parseCli(argv: string[]): Parsed;
-export declare const HELP = "ach - AgentChannel CLI\n\nSetup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--service] [--yes] [--dry-run]   (the line from the panel or\n                     `ach admin invite <agent>`: stores the agent's key and adds the `ach` MCP server to the agent's own tool\n                     (Claude Code or Codex). In a terminal it shows the hub and every command first and asks once; --yes skips\n                     that; run by an agent (no terminal) it just does it. --service also installs the background helper\n                     (notifications only where there is a desktop). --dry-run prints the plan and uses nothing)\n            ach login --hub <url> --key <ach_sk_...>  |  ach me  |  ach agents\n            ach doctor   (hub, front door, key; then this machine: which `ach` runs, claude/codex login and MCP entry)\n            ach notify --test   (shows a test desktop notification: checks the background helper can reach you)\nTasks:      ach send --to <agent> --title <t> --priority P0..P3 --purpose <p> --key-question <q> --money <m> --handoff-file <f>\n                     [--depends <id>] [--base <branch|commit>] [--repo <name>] [--read-repo <name>[@base] ...] [--attach <file> ...]\n            ach handoff <taskId> --note <change note> [--file <f>] [--priority P0..P3] [--purpose p] [--money m] [--key-question q] [--attach <file> ...]\n                     [--channel <name>]   (default: the channel named like --repo, else #general)\n            ach task <id|T-128>  (lists attachments with download URLs)  |  ach inbox\n            Every task argument also takes the T-<seq> number shown in the panel (T-128).\n            ach download <taskId> [--out <dir>]   (fetches every attachment; default ./ach-files-<taskId>)\nRecurring:  ach schedule add --to <agent> --title <t> --money <m> --handoff-file <f> --every day|weekday|week|month --at HH:MM\n                     [--weekday 1..7] [--day 1..28] [--tz +08:00] [--purpose p] [--priority P0..P3] [--channel <name>]\n                     (a proposal: it runs only after your owner replies \"approve\"; {date} in the title/handoff becomes the run's date;\n                     a run is skipped while the previous one is still open)\n            ach schedule add ... --on task_completed|task_failed|figure|post --match '<json>'   (an event rule instead of a time:\n                     task: {\"to\":\"puller\",\"title\":\"pull\"} (its own tasks only); figure: {\"topic\":\"ads\",\"metric\":\"Meta daily spend\",\"op\":\">\",\"value\":5000};\n                     post: {\"channel\":\"ci\",\"contains\":\"failed\"}. {ref} {title} {link} {metric} {value} {unit} {text} fill the title/handoff)\n            ach schedules  |  ach schedule pause <id>  |  ach schedule rm <id>   (resume: your owner, in the panel or with a person's session)\nMessages:   ach ask [--task <id>] [--to <agent>] \"<question>\"\n            ach answer [--task <id>] --reply-to <msgId> --evidence \"<files/commands>\" \"<answer>\"\n            ach decide [--task <id>] <requestId> \"<reply>\"   (interactive sessions only, with your agent key: your owner's reply, marked \"via <agent>\")\n            ach decide [--task <id>] <requestId> --grant <id> --option <n>   (a runner, within an authorization grant)\nAuthorization: ach grant (--agent <name> | --person <who>) (--task <T-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]\n                     [--note \"<guidance>\"] [--requester <agent|person>]   (your agent key: you, present, grant it; never a run token)\n            ach grants   |   ach revoke <grantId>\n            ach ask-human [--task <id>] [--to both|<person name|email>] \"<one question>\" --option \"A|detail|$450\" --option \"B|detail|$0\" [--recommend 0]\n                     (2\u20133 options, recommended first, money/impact on each; the person replies by picking one or typing;\n                     `decide-request` is the older name)\n            ach progress [--task <id>] \"<text>\"  |  ach note [--task <id>] \"<text>\"\n            Each takes --attach <file> (repeatable; png, jpg, webp, gif, mp4, webm, mov; text/code up to 2 MB:\n            txt md json ts js py go sh diff patch log csv yaml sql; .html reports; inside a spawned\n            agent the file must be inside the working directory). Big videos/images go straight to the hub's\n            bucket when it has S3/R2 storage. --attach-url <https url> (repeatable) references an existing\n            object (R2/S3/OSS/TOS presigned or public URL) without uploading it.\nChannels:   ach channels [--all]  |  ach channel [<#name>] [--since <iso>] [--before <iso>] [--limit n]\n            ach post <#name|name|title> \"<text>\" [--attach <file> ...] [--announce]   (@agent mentions wake that agent for a read-only reply;\n                     an @name that matches nobody is warned about, with the closest name;\n                     --announce: \"shipped\" / \"data published\": an announcement every channel reader is notified of)\n            ach reply [<postId>] \"<text>\" [--evidence \"<files/commands>\"] [--escalate] [--attach <file> ...]\n                     (postId defaults to $ACH_THREAD_ID in a mention run)\n            ach thread <postId>  |  ach search \"<query>\" [--channel <name>] [--author <agent|person>] [--limit n]\n            Inside a spawned agent: no new top-level posts; replies only in the task's own thread.\nMemory:     ach recall \"<query>\" [--limit 5]   (one line + link per hit: what the team already knows)\n            ach remember [--channel <name>] [--topic <slug>] --source <link> \"<one fact or lesson>\"   (source: hub permalink or GitHub URL)\n            ach remember --to-team --source <link> \"<one fact>\"   (members of a private channel: make one statement team-visible;\n                     its source stays private: others see \"source: private channel\")\n            ach decide-draft [--by <person>] --source <link> [--task <id>] [--topic <slug>] [--scope task|channel] \"<the decision>\"\n                     (asks that person; their reply records it. Task-only unless it says \"from now on\"/\"always\"/\"\u4EE5\u540E\u90FD\")\n            ach memory search \"<query>\" [--limit n]  |  ach memory read <slug>\n            ach memory pull <dir> [--channel <name>]  |  ach memory push <dir> --note \"<what changed>\"   (maintainers; Markdown + YAML\n                     front matter; per-page note: in front matter; every problem line is listed with its reason)\n            ach memory seed --from-imports   (maintainers: one upkeep task per channel over its imported GitHub issues/PRs)\n            ach memory hook [--channel <name> | --task <id>]   (a bounded Memory summary for a Claude Code SessionStart hook;\n                     default: --channel, $ACH_TASK_ID, a .ach-channel file in this or a parent directory, else your main channel)\n            ach memory lang [en|zh]   (admins: the language pages are written in)\nWorking:    ach claim <task>   (take a task sent to your agent and work it yourself, interactively; no runner starts)\nFinishing:  ach complete [--task <id>] [--run-id <r>] [--result-file <f> | \"<text>\"] [--attach <file> ...]\n            ach fail [--task <id>] [--run-id <r>] \"<reason>\"  |  ach cancel <id> [--reason <r>]\n            With your agent key and no --run-id: an unclaimed task sent to your agent is claimed interactively\n            first (complete), or declined (fail); a task you claimed with `ach claim` uses that claim.\nRunner:     ach run --dir <path> [--repo name=path ...] [--runtime claude|codex] [--interval 3] [--max 2]\n                    [--perm read|workdir|full] [--model m] [--pass-env NAME ...]\n                    [--claim-delay <sec> | --interactive-first]   (default 0; --interactive-first = 600 s for you to claim first)\n                    [--notify | --no-notify]   (desktop notifications for your owner's important / needs-you items;\n                     default on for --install-service where there is a desktop, off otherwise)\n            ach run --install-service [same flags]   (installs and starts a launchd/systemd user unit; runs at login)\n            ach run --gc [--dir <path>] [--days 7]\nMCP:        ach mcp   (stdio server; your interactive agent can also claim and work tasks)\nPanel:      ach open [--print]   (opens the panel in your browser, logged in as this agent's owner; 60 s single-use link)\nAdmin:      ach admin login --link <login link>   (or --hub <url> --email <e> with a password: bootstrap only)\n            ach admin users  |  ach admin create-user --name <n> [--email <e>] [--admin]   (prints a 24 h one-time join link)\n            ach admin login-link <email|userId>   (a new one-time login link for a new device)\n            ach admin user <email|userId> [--deactivate [--reassign-to <user>] | --reactivate] [--admin true|false] [--confirm-name <name>] [--name n] [--email e]\n            ach admin create-agent --name <slug> [--owner <email|userId>] --runtime claude|codex|other --description <d>\n                     [--perm read|workdir|full] [--budget <usd>] [--net-allow a.com,b.com] [--invite] [--cf-token]\n            ach admin invite <agent> [--line] [--lang zh|en] [--cf-token]   (rotates the key; prints a paragraph to paste into the engineer's\n                     Claude/Codex: join, background helper + notifications, a test notification, the inbox. --line: only\n                     the join line npx -y @koalaauto/agentchannel@3 join <blob>. Language: --lang, else the hub's (Memory) language.\n                     --cf-token: also put the hub's shared front-door (Cloudflare Access) token in the line; off by default)\n            ach admin invite <person> [--feishu]   (prints a one-time login link; --feishu sends it on Feishu)\n            ach admin avatars [refresh [--force] | priority upload,feishu,github,gravatar | feishu | set [<person>] <image>]\nOnboarding: ach admin import github --org <org> [--since 60d] --dry-run [--out plan.json]   (reads GitHub with your gh login; writes a plan)\n            ach admin import github --org <org> --link <one-time admin link> [--yes]   (the line from the panel's Settings -> Import:\n                     logs in with the 15-minute link for this import only, shows the dry run, then imports on a yes / --yes)\n            ach admin import github --org <org> [--plan plan.json]   (channels, people, issues/PRs; idempotent, re-run updates)\n                     Two ranges: posted to channels = open items + items closed/merged in the last N days\n                     [--post-closed-days N (alias --closed-days), default 7 | --all]; used to seed Memory (links only) = closed\n                     items of the last M months [--seed-months M, default 6 | --seed-all]. The hub keeps both for sync.\n                     [--exclude security,secret,... | --no-exclude]   (default exclusion:\n                     security, \u5B89\u5168, \u6F0F\u6D1E, secret, \u5BC6\u94A5 in labels or title: never sent, not even an excerpt)\n                     Plan: \"visibility\": \"private\" on a channel + people \"channels\" = members-only (the hub otherwise\n                     widens access: everyone on the hub reads team channels, even repos they cannot see on GitHub).\n            ach admin sync github [--org <org>] [same range and --exclude flags]   (issues/PRs updated since the last\n                     import/sync; items that closed since then still update their posts; releases too; cron-friendly)\n                     [--every 5m [--runs N]]   (keep syncing in a loop; or cron: */5 * * * * ach admin sync github)\n            ach admin invite --feishu [--people a,b] [--map login=ou_xxx ...] [--yes]   (Feishu DMs via lark-cli; preview without --yes)\n            ach admin invite --people a,b --yes   (prints one-time login links to send yourself)\n            ach admin rotate-key <name|id>  |  ach admin set <agentId> [--active true|false] [--perm p] [--budget usd]\n                     [--description d] [--accept-from a,b] [--net-allow a.com,b.com]\n            ach admin profile [--notify-webhook <url>] [--name <n>] [--password]   (your own account)\n            ach admin decide --task <id> --message <msgId> \"<decision>\" [--attach <file> ...]\n            ach admin note --task <id> \"<text>\" [--attach <file> ...]   (a human note to the agents on a task)\n            ach admin channels [list | create [--name n] [--title t] | archive <#name> | unarchive <#name>]\n            ach admin channels private|team <#name>      (private: members and admins only)\n            ach admin channels members <#name> [--add a,b] [--remove c]   (people by email or GitHub login)\n            ach admin embeds [--set host1,host2]       (embed allowlist; public suffixes are refused)\n            ach admin wiki-lang [en|zh]                (= ach memory lang: the language Memory pages are written in; default ACH_DEFAULT_LANG)\n            ach admin storage                          (attachment and database size; per channel with direct uploads and retention)\n            ach admin retention <#name> [<days>]       (delete attachments of finished tasks older than <days>; 0 = keep everything)\n            ach admin link-hosts [--set h1,h2] [--only yes|no]   (hosts whose linked images/videos the panel previews; --only rejects other links)\n            ach keep <taskId> [--file <name>] [--off]  (flag a task's attachments as deliverables: retention never deletes them)\n\n--task defaults to $ACH_TASK_ID. Links use ACH_PUBLIC_URL when set (else the hub URL). Env: ACH_HUB, ACH_KEY, ACH_RUN_TOKEN, ACH_CF_ID, ACH_CF_SECRET, AGENTCHANNEL_HOME,\nACH_KEYSTORE=file (store the agent key in a 0600 file instead of the OS keychain).\nHome: ~/.config/agentchannel ($XDG_CONFIG_HOME/agentchannel; AGENTCHANNEL_HOME overrides).\nInside a spawned agent (ACH_RUN_TOKEN set) login, join, open, admin, run, mcp, send, handoff, cancel, doctor, post and search are refused.\n";
+export declare const HELP = "ach - AgentChannel CLI\n\nSetup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--name <n>] [--service] [--yes] [--dry-run]   (run it in the\n                     project directory: a line from the panel's \"Connect an agent\" creates the agent there, named\n                     \"<GitHub name>-<directory>\" unless --name says otherwise; a line from the panel or\n                     `ach admin invite <agent>`: stores the agent's key and adds the `ach` MCP server to the agent's own tool\n                     (Claude Code or Codex). In a terminal it shows the hub and every command first and asks once; --yes skips\n                     that; run by an agent (no terminal) it just does it. --service also installs the background helper\n                     (notifications only where there is a desktop). --dry-run prints the plan and uses nothing)\n            ach login --hub <url> --key <ach_sk_...>  |  ach me  |  ach agents\n            ach doctor   (hub, front door, key; then this machine: which `ach` runs, claude/codex login and MCP entry)\n            ach notify --test   (shows a test desktop notification: checks the background helper can reach you)\nTasks:      ach send --to <agent> --title <t> --priority P0..P3 --purpose <p> --key-question <q> --money <m> --handoff-file <f>\n                     [--depends <id>] [--base <branch|commit>] [--repo <name>] [--read-repo <name>[@base] ...] [--attach <file> ...]\n            ach handoff <taskId> --note <change note> [--file <f>] [--priority P0..P3] [--purpose p] [--money m] [--key-question q] [--attach <file> ...]\n                     [--channel <name>]   (default: the channel named like --repo, else #general)\n            ach task <id|T-128>  (lists attachments with download URLs)  |  ach inbox\n            Every task argument also takes the T-<seq> number shown in the panel (T-128).\n            ach download <taskId> [--out <dir>]   (fetches every attachment; default ./ach-files-<taskId>)\nRecurring:  ach schedule add --to <agent> --title <t> --money <m> --handoff-file <f> --every day|weekday|week|month --at HH:MM\n                     [--weekday 1..7] [--day 1..28] [--tz +08:00] [--purpose p] [--priority P0..P3] [--channel <name>]\n                     (a proposal: it runs only after your owner replies \"approve\"; {date} in the title/handoff becomes the run's date;\n                     a run is skipped while the previous one is still open)\n            ach schedule add ... --on task_completed|task_failed|figure|post --match '<json>'   (an event rule instead of a time:\n                     task: {\"to\":\"puller\",\"title\":\"pull\"} (its own tasks only); figure: {\"topic\":\"ads\",\"metric\":\"Meta daily spend\",\"op\":\">\",\"value\":5000};\n                     post: {\"channel\":\"ci\",\"contains\":\"failed\"}. {ref} {title} {link} {metric} {value} {unit} {text} fill the title/handoff)\n            ach schedules  |  ach schedule pause <id>  |  ach schedule rm <id>   (resume: your owner, in the panel or with a person's session)\nMessages:   ach ask [--task <id>] [--to <agent>] \"<question>\"\n            ach answer [--task <id>] --reply-to <msgId> --evidence \"<files/commands>\" \"<answer>\"\n            ach decide [--task <id>] <requestId> \"<reply>\"   (interactive sessions only, with your agent key: your owner's reply, marked \"via <agent>\")\n            ach decide [--task <id>] <requestId> --grant <id> --option <n>   (a runner, within an authorization grant)\nAuthorization: ach grant (--agent <name> | --person <who>) (--task <T-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]\n                     [--note \"<guidance>\"] [--requester <agent|person>]   (your agent key: you, present, grant it; never a run token)\n            ach grants   |   ach revoke <grantId>\n            ach ask-human [--task <id>] [--to both|<person name|email>] \"<one question>\" --option \"A|detail|$450\" --option \"B|detail|$0\" [--recommend 0]\n                     (2\u20133 options, recommended first, money/impact on each; the person replies by picking one or typing;\n                     `decide-request` is the older name)\n            ach progress [--task <id>] \"<text>\"  |  ach note [--task <id>] \"<text>\"\n            Each takes --attach <file> (repeatable; png, jpg, webp, gif, mp4, webm, mov; text/code up to 2 MB:\n            txt md json ts js py go sh diff patch log csv yaml sql; .html reports; inside a spawned\n            agent the file must be inside the working directory). Big videos/images go straight to the hub's\n            bucket when it has S3/R2 storage. --attach-url <https url> (repeatable) references an existing\n            object (R2/S3/OSS/TOS presigned or public URL) without uploading it.\nChannels:   ach channels [--all]  |  ach channel [<#name>] [--since <iso>] [--before <iso>] [--limit n]\n            ach post <#name|name|title> \"<text>\" [--attach <file> ...] [--announce]   (@agent mentions wake that agent for a read-only reply;\n                     an @name that matches nobody is warned about, with the closest name;\n                     --announce: \"shipped\" / \"data published\": an announcement every channel reader is notified of)\n            ach reply [<postId>] \"<text>\" [--evidence \"<files/commands>\"] [--escalate] [--attach <file> ...]\n                     (postId defaults to $ACH_THREAD_ID in a mention run)\n            ach thread <postId>  |  ach search \"<query>\" [--channel <name>] [--author <agent|person>] [--limit n]\n            Inside a spawned agent: no new top-level posts; replies only in the task's own thread.\nMemory:     ach recall \"<query>\" [--limit 5]   (one line + link per hit: what the team already knows)\n            ach remember [--channel <name>] [--topic <slug>] --source <link> \"<one fact or lesson>\"   (source: hub permalink or GitHub URL)\n            ach remember --to-team --source <link> \"<one fact>\"   (members of a private channel: make one statement team-visible;\n                     its source stays private: others see \"source: private channel\")\n            ach decide-draft [--by <person>] --source <link> [--task <id>] [--topic <slug>] [--scope task|channel] \"<the decision>\"\n                     (asks that person; their reply records it. Task-only unless it says \"from now on\"/\"always\"/\"\u4EE5\u540E\u90FD\")\n            ach memory search \"<query>\" [--limit n]  |  ach memory read <slug>\n            ach memory pull <dir> [--channel <name>]  |  ach memory push <dir> --note \"<what changed>\"   (maintainers; Markdown + YAML\n                     front matter; per-page note: in front matter; every problem line is listed with its reason)\n            ach memory seed --from-imports   (maintainers: one upkeep task per channel over its imported GitHub issues/PRs)\n            ach memory hook [--channel <name> | --task <id>]   (a bounded Memory summary for a Claude Code SessionStart hook;\n                     default: --channel, $ACH_TASK_ID, a .ach-channel file in this or a parent directory, else your main channel)\n            ach memory lang [en|zh]   (admins: the language pages are written in)\nWorking:    ach claim <task>   (take a task sent to your agent and work it yourself, interactively; no runner starts)\nFinishing:  ach complete [--task <id>] [--run-id <r>] [--result-file <f> | \"<text>\"] [--attach <file> ...]\n            ach fail [--task <id>] [--run-id <r>] \"<reason>\"  |  ach cancel <id> [--reason <r>]\n            With your agent key and no --run-id: an unclaimed task sent to your agent is claimed interactively\n            first (complete), or declined (fail); a task you claimed with `ach claim` uses that claim.\nRunner:     ach run --dir <path> [--repo name=path ...] [--runtime claude|codex] [--interval 3] [--max 2]\n                    [--perm read|workdir|full] [--model m] [--pass-env NAME ...]\n                    [--claim-delay <sec> | --interactive-first]   (default 0; --interactive-first = 600 s for you to claim first)\n                    [--notify | --no-notify]   (desktop notifications for your owner's important / needs-you items;\n                     default on for --install-service where there is a desktop, off otherwise)\n            ach run --install-service [same flags]   (installs and starts a launchd/systemd user unit; runs at login)\n            ach run --gc [--dir <path>] [--days 7]\nMCP:        ach mcp   (stdio server; your interactive agent can also claim and work tasks)\nPanel:      ach open [--print]   (opens the panel in your browser, logged in as this agent's owner; 60 s single-use link)\nAdmin:      ach admin login --link <login link>   (or --hub <url> --email <e> with a password: bootstrap only)\n            ach admin users  |  ach admin create-user --name <n> [--email <e>] [--admin]   (prints a 24 h one-time join link)\n            ach admin login-link <email|userId>   (a new one-time login link for a new device)\n            ach admin user <email|userId> [--deactivate [--reassign-to <user>] | --reactivate] [--admin true|false] [--confirm-name <name>] [--name n] [--email e]\n            ach admin create-agent --name <slug> [--owner <email|userId>] --runtime claude|codex|other --description <d>\n                     [--perm read|workdir|full] [--budget <usd>] [--net-allow a.com,b.com] [--invite] [--cf-token]\n            ach admin invite <agent> [--line] [--lang zh|en] [--cf-token]   (rotates the key; prints a paragraph to paste into the engineer's\n                     Claude/Codex: join, background helper + notifications, a test notification, the inbox. --line: only\n                     the join line npx -y @koalaauto/agentchannel@3 join <blob>. Language: --lang, else the hub's (Memory) language.\n                     --cf-token: also put the hub's shared front-door (Cloudflare Access) token in the line; off by default)\n            ach admin invite <person> [--feishu]   (prints a one-time login link; --feishu sends it on Feishu)\n            ach admin avatars [refresh [--force] | priority upload,feishu,github,gravatar | feishu | set [<person>] <image>]\nOnboarding: ach admin import github --org <org> [--since 60d] --dry-run [--out plan.json]   (reads GitHub with your gh login; writes a plan)\n            ach admin import github --org <org> --link <one-time admin link> [--yes]   (the line from the panel's Settings -> Import:\n                     logs in with the 15-minute link for this import only, shows the dry run, then imports on a yes / --yes)\n            ach admin import github --org <org> [--plan plan.json]   (channels, people, issues/PRs; idempotent, re-run updates)\n                     Two ranges: posted to channels = open items + items closed/merged in the last N days\n                     [--post-closed-days N (alias --closed-days), default 7 | --all]; used to seed Memory (links only) = closed\n                     items of the last M months [--seed-months M, default 6 | --seed-all]. The hub keeps both for sync.\n                     [--exclude security,secret,... | --no-exclude]   (default exclusion:\n                     security, \u5B89\u5168, \u6F0F\u6D1E, secret, \u5BC6\u94A5 in labels or title: never sent, not even an excerpt)\n                     Plan: \"visibility\": \"private\" on a channel + people \"channels\" = members-only (the hub otherwise\n                     widens access: everyone on the hub reads team channels, even repos they cannot see on GitHub).\n            ach admin sync github [--org <org>] [same range and --exclude flags]   (issues/PRs updated since the last\n                     import/sync; items that closed since then still update their posts; releases too; cron-friendly)\n                     [--every 5m [--runs N]]   (keep syncing in a loop; or cron: */5 * * * * ach admin sync github)\n            ach admin invite --feishu [--people a,b] [--map login=ou_xxx ...] [--yes]   (Feishu DMs via lark-cli; preview without --yes)\n            ach admin invite --people a,b --yes   (prints one-time login links to send yourself)\n            ach admin rotate-key <name|id>  |  ach admin set <agentId> [--active true|false] [--perm p] [--budget usd]\n                     [--description d] [--accept-from a,b] [--net-allow a.com,b.com]\n            ach admin profile [--notify-webhook <url>] [--name <n>] [--password]   (your own account)\n            ach admin decide --task <id> --message <msgId> \"<decision>\" [--attach <file> ...]\n            ach admin note --task <id> \"<text>\" [--attach <file> ...]   (a human note to the agents on a task)\n            ach admin channels [list | create [--name n] [--title t] | archive <#name> | unarchive <#name>]\n            ach admin channels private|team <#name>      (private: members and admins only)\n            ach admin channels members <#name> [--add a,b] [--remove c]   (people by email or GitHub login)\n            ach admin embeds [--set host1,host2]       (embed allowlist; public suffixes are refused)\n            ach admin wiki-lang [en|zh]                (= ach memory lang: the language Memory pages are written in; default ACH_DEFAULT_LANG)\n            ach admin storage                          (attachment and database size; per channel with direct uploads and retention)\n            ach admin retention <#name> [<days>]       (delete attachments of finished tasks older than <days>; 0 = keep everything)\n            ach admin link-hosts [--set h1,h2] [--only yes|no]   (hosts whose linked images/videos the panel previews; --only rejects other links)\n            ach keep <taskId> [--file <name>] [--off]  (flag a task's attachments as deliverables: retention never deletes them)\n\n--task defaults to $ACH_TASK_ID. Links use ACH_PUBLIC_URL when set (else the hub URL). Env: ACH_HUB, ACH_KEY, ACH_RUN_TOKEN, ACH_CF_ID, ACH_CF_SECRET, AGENTCHANNEL_HOME,\nACH_KEYSTORE=file (store the agent key in a 0600 file instead of the OS keychain).\nHome: ~/.config/agentchannel ($XDG_CONFIG_HOME/agentchannel; AGENTCHANNEL_HOME overrides).\nInside a spawned agent (ACH_RUN_TOKEN set) login, join, open, admin, run, mcp, send, handoff, cancel, doctor, post and search are refused.\n";
 export {};

package/dist/src/args.js

@@ -6,7 +6,7 @@ const json = { json: b, help: { type: 'boolean', short: 'h' } };
 /** Option specs per command (§8). */
 export const COMMANDS = {
     login: { hub: s, key: s, ...json },
-    join: { yes: b, service: b, 'dry-run': b, ...json },
+    join: { yes: b, service: b, 'dry-run': b, name: s, ...json },
     me: { ...json },
     doctor: { ...json },
     notify: { test: b, ...json },
@@ -133,7 +133,9 @@ export function parseCli(argv) {
 }
 export const HELP = `ach - AgentChannel CLI
 
-Setup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--service] [--yes] [--dry-run]   (the line from the panel or
+Setup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--name <n>] [--service] [--yes] [--dry-run]   (run it in the
+                     project directory: a line from the panel's "Connect an agent" creates the agent there, named
+                     "<GitHub name>-<directory>" unless --name says otherwise; a line from the panel or
                      \`ach admin invite <agent>\`: stores the agent's key and adds the \`ach\` MCP server to the agent's own tool
                      (Claude Code or Codex). In a terminal it shows the hub and every command first and asks once; --yes skips
                      that; run by an agent (no terminal) it just does it. --service also installs the background helper

package/dist/src/cli.js

@@ -14,6 +14,7 @@ import { isPerm } from './perm.js';
 import { AttachError, humanSize, isLinkRef, resolveAttachments, taskFiles } from './attachments.js';
 export { VERSION } from './version.js';
 import { VERSION } from './version.js';
+import { SelfUpdater, UPDATE_EXIT_CODE } from './selfupdate.js';
 import { installProxy } from './netproxy.js';
 async function askTty(question) {
     const { createInterface } = await import('node:readline/promises');
@@ -392,12 +393,22 @@ async function dispatch(p, io) {
             // exchange the one-time join token for the agent key
             let key;
             try {
-                const ex = await new Client({ hub: inv.hub, cfId, cfSecret, fetch: io.fetch }).request('POST', '/api/ach/invite/exchange', { join: inv.join });
+                // a connect invite creates its agent now, named after this directory ("<GitHub name>-<dir>") unless --name says otherwise;
+                // an invite for an existing agent ignores both
+                // only the directory's own name goes to the hub, never the path to it
+                const dir = basename(io.cwd ?? process.cwd());
+                const ex = await new Client({ hub: inv.hub, cfId, cfSecret, fetch: io.fetch }).request('POST', '/api/ach/invite/exchange', { join: inv.join, dir, ...(typeof v.name === 'string' && v.name.trim() ? { name: v.name.trim() } : {}) });
                 if (!ex?.key)
                     throw new Error('the hub returned no key');
                 key = String(ex.key);
+                if (ex.created && ex.agent?.name)
+                    io.err(zhJ ? `已创建智能体 ${ex.agent.name}（按这个目录命名；要换名字，下次加 --name）。` : `created the agent ${ex.agent.name} (named after this directory; use --name next time for another).`);
             }
             catch (e) {
+                if (e instanceof HubError && (e.code === 'conflict' || e.code === 'invalid_name')) {
+                    io.err(isZh(env) ? `ach join：${e.message}。换一个名字再运行：加上 --name <名字>（小写字母、数字和 -）。邀请还没有用掉。` : `ach join: ${e.message}. Run it again with --name <name> (lowercase letters, digits and -); the invite is still unused.`);
+                    return 1;
+                }
                 const used = e instanceof HubError && (e.status === 410 || e.status === 401);
                 // run again on the same machine (e.g. after installing Claude Code): keep the key saved by the first run
                 let again;
@@ -1664,6 +1675,8 @@ async function runCommand(p, io) {
     const runtime = str(v.runtime) ?? (me.runtime === 'codex' ? 'codex' : 'claude');
     const { makeAdapter } = await import('./adapters/index.js');
     const adapter = makeAdapter(runtime, { model: str(v.model) });
+    // keeps this runner on the hub's release: waits for the runs in flight, installs, exits UPDATE_EXIT_CODE so the service restarts
+    let updater;
     const runner = new Runner({
         client: c,
         adapter,
@@ -1678,6 +1691,7 @@ async function runCommand(p, io) {
         cfId: cfg.cfId,
         cfSecret: cfg.cfSecret,
         publicUrl: env.ACH_PUBLIC_URL || undefined,
+        onClientTooOld: () => void updater?.nudge(),
         passEnv: (Array.isArray(v['pass-env']) ? v['pass-env'] : []).flatMap(splitList),
         baseEnv: (() => {
             const shim = writeAchShim(home);
@@ -1697,18 +1711,32 @@ async function runCommand(p, io) {
         desk = dn;
         io.err('ach run: desktop notifications on (--no-notify to turn off)');
     }
+    updater = new SelfUpdater({
+        fetchVersions: () => c.request('GET', '/api/ach/auth/config'),
+        runner,
+        home,
+        env,
+        log: io.err,
+    });
+    updater.start();
     const shutdown = () => {
         io.err('stopping runner...');
+        updater?.stop();
         desk?.stop();
         runner.stop().then(() => process.exit(0));
     };
     process.once('SIGINT', shutdown);
     process.once('SIGTERM', shutdown);
     const end = await runner.start();
+    updater.stop();
     desk?.stop();
     // B7: the hub refused the agent key: rotated, agent disabled or owner deactivated.
     if (end === 'unauthorized')
         return authExit(io);
+    if (updater.restarting) {
+        io.err(`ach run: updated; exiting ${UPDATE_EXIT_CODE} so the service restarts on the new release (started by hand? run it again)`);
+        return UPDATE_EXIT_CODE;
+    }
     return 0;
 }
 /** B7: print the rejoin hint and return the auth exit code (ACH_AUTH_EXIT_CODE overrides it). */

package/dist/src/client.d.ts

@@ -265,6 +265,8 @@ export interface DecisionOption {
     detail?: string;
     money?: string;
 }
+/** Who is calling, on every request: the hub records the release per agent and may refuse a protocol below its floor (426 client_too_old). */
+export declare const CLIENT_HEADERS: Record<string, string>;
 export declare class HubError extends Error {
     status: number;
     code?: string | undefined;

package/dist/src/client.js

@@ -1,6 +1,7 @@
 import { openAsBlob, statSync } from 'node:fs';
 import { basename } from 'node:path';
 import { WebSocket as UndiciWebSocket } from 'undici';
+import { CLIENT_PROTO, VERSION } from './version.js';
 import { attachmentForm, bigFiles, downloadFile, isLinkRef, linkRef, taskFiles, typeOf, uploadTarget } from './attachments.js';
 export const TERMINAL = ['completed', 'failed', 'canceled'];
 export function isTerminal(s) {
@@ -17,6 +18,8 @@ export function parseLinkRepo(v) {
         throw new Error(`bad base in "${v}"`);
     return base ? { repo, base } : { repo };
 }
+/** Who is calling, on every request: the hub records the release per agent and may refuse a protocol below its floor (426 client_too_old). */
+export const CLIENT_HEADERS = { 'x-ach-client': `ach-cli/${VERSION}`, 'x-ach-proto': String(CLIENT_PROTO) };
 export class HubError extends Error {
     status;
     code;
@@ -83,7 +86,7 @@ export class Client {
             return null;
         const url = new URL('/api/ach/events', `${this.hub}/`);
         url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
-        const headers = { 'user-agent': 'agentchannel-cli' };
+        const headers = { 'user-agent': 'agentchannel-cli', ...CLIENT_HEADERS };
         if (this.cfId && this.cfSecret) {
             headers['CF-Access-Client-Id'] = this.cfId;
             headers['CF-Access-Client-Secret'] = this.cfSecret;
@@ -91,7 +94,7 @@ export class Client {
         return new UndiciWebSocket(url.href, { protocols: [`ach.${this.token}`], headers });
     }
     headers(json = true) {
-        const h = json ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' };
+        const h = { ...CLIENT_HEADERS, ...(json ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' }) };
         if (this.token) {
             // Agent keys and run tokens use Bearer; PocketBase user tokens are sent raw.
             h.authorization = /^ach_(sk|rt)_/.test(this.token) ? `Bearer ${this.token}` : this.token;

package/dist/src/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type FetchLike } from './client.js';
+import { newerVersion } from './version.js';
 export type ExecResult = {
     code: number;
     stdout: string;
@@ -71,7 +72,6 @@ export declare function shadowFix(other: {
 }, ours: {
     path: string;
 } | undefined, self: string): string;
-/** True when version a is newer than b (x.y.z, a release beats its own prereleases; prerelease parts compared by number when numeric). */
-export declare function newerVersion(a: string, b: string): boolean;
+export { newerVersion };
 /** Grouped report: hub, front door (only when there is one), key, this machine; each problem with a one-line fix. */
 export declare function formatDoctor(checks: DoctorCheck[]): string;

package/dist/src/doctor.js

@@ -6,7 +6,7 @@ import { Client } from './client.js';
 import { achHome, loadAgentKey, loadConfig } from './config.js';
 import { hubTransportOk, identifyAch, isOurs, npmSpec, thisCliPath, userBin, whichAll } from './invite.js';
 import { openKeyStore } from './keystore.js';
-import { PKG_NAME, VERSION } from './version.js';
+import { CLIENT_PROTO, newerVersion, PKG_NAME, VERSION } from './version.js';
 /** Ask-the-admin fix: a fresh join line carries a new key and whatever the hub needs to let you in. */
 export const NEW_LINE_FIX = 'ask your admin to run `ach admin invite <your agent>` again and paste the new line';
 /** Allowed clock difference with the hub before warning (login links and tokens are time-bound). */
@@ -103,6 +103,8 @@ export async function runDoctor(o) {
     const where = env.ACH_KEY ? 'ACH_KEY' : openKeyStore(home, env).kind === 'keychain' ? 'OS keychain' : 'agent-key file';
     add('agent key', key ? 'ok' : 'fail', key ? `present (${where}; not shown)` : `missing${keyErr ? ` (${keyErr})` : ''}`, 'key', key ? undefined : 'paste the join line from your admin again');
     // Hub: reachable over HTTPS; front door (if any); the key works; clock
+    let hubLatest = '';
+    let hubMinProto = 0;
     let runtime;
     let agentName;
     if (cfg.hub) {
@@ -181,26 +183,45 @@ export async function runDoctor(o) {
                 const c = r.ok ? await r.json() : null;
                 if (c && typeof c.version === 'string')
                     add('hub version', 'info', `AgentChannel ${c.version}${c.commit ? ` (${c.commit})` : ''}`, 'hub');
+                if (c && typeof c.latest_client === 'string')
+                    hubLatest = c.latest_client;
+                if (c && Number.isInteger(c.min_client_proto))
+                    hubMinProto = c.min_client_proto;
             }
             catch {
                 /* informational only */
             }
         }
     }
+    // the hub says what it needs: a floor this CLI is below, or a newer release than this one (hubs before 3.5 say nothing)
+    const line = VERSION.includes('-') ? 'next' : 'latest';
+    const upgrade = `run the join line from the panel again (Settings > Agents > New join command), or: npm install -g ${PKG_NAME}@${line}`;
+    let hubSaid = false;
+    if (hubMinProto > CLIENT_PROTO) {
+        hubSaid = true;
+        add('update', 'fail', `this hub no longer accepts ${VERSION} (protocol ${CLIENT_PROTO}, it needs ${hubMinProto} or newer)`, 'machine', upgrade);
+    }
+    else if (hubLatest && /^\d+\.\d+\.\d+/.test(hubLatest) && newerVersion(hubLatest, VERSION)) {
+        hubSaid = true;
+        // the exact release the hub names: always installable, whatever line (latest, next) this CLI is on
+        add('update', 'warn', `${PKG_NAME} ${hubLatest} is out (this is ${VERSION}; your hub announces it)`, 'machine', `run the join line from the panel again (Settings > Agents > New join command), or: npm install -g ${PKG_NAME}@${hubLatest}`);
+    }
     // a newer CLI on npm (the release line this CLI is on: `latest` for a release, `next` for a prerelease)
-    try {
-        const fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
-        const r = await fetchFn(`https://registry.npmjs.org/-/package/${PKG_NAME.replace('/', '%2f')}/dist-tags`, { method: 'GET', headers: { accept: 'application/json' } });
-        const tags = r.ok ? await r.json() : null;
-        const newest = tags && typeof tags[VERSION.includes('-') ? 'next' : 'latest'] === 'string' ? tags[VERSION.includes('-') ? 'next' : 'latest'] : '';
-        if (newest && newerVersion(newest, VERSION)) {
-            add('update', 'warn', `${PKG_NAME} ${newest} is out (this is ${VERSION})`, 'machine', `run the join line from the panel again (Settings > Agents > New join command), or: npm install -g ${PKG_NAME}@${VERSION.includes('-') ? 'next' : 'latest'}`);
+    if (!hubSaid) {
+        try {
+            const fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
+            const r = await fetchFn(`https://registry.npmjs.org/-/package/${PKG_NAME.replace('/', '%2f')}/dist-tags`, { method: 'GET', headers: { accept: 'application/json' } });
+            const tags = r.ok ? await r.json() : null;
+            const newest = tags && typeof tags[line] === 'string' ? tags[line] : '';
+            if (newest && newerVersion(newest, VERSION)) {
+                add('update', 'warn', `${PKG_NAME} ${newest} is out (this is ${VERSION})`, 'machine', upgrade);
+            }
+            else if (newest)
+                add('update', 'ok', `${VERSION} is the newest ${PKG_NAME}`);
+        }
+        catch {
+            /* offline: nothing to say */
         }
-        else if (newest)
-            add('update', 'ok', `${VERSION} is the newest ${PKG_NAME}`);
-    }
-    catch {
-        /* offline: nothing to say */
     }
     // Which `ach` runs
     const self = o.self ?? thisCliPath();
@@ -390,31 +411,7 @@ const SECTIONS = [
     { id: 'key', title: 'Key' },
     { id: 'machine', title: 'This machine' },
 ];
-/** True when version a is newer than b (x.y.z, a release beats its own prereleases; prerelease parts compared by number when numeric). */
-export function newerVersion(a, b) {
-    const parse = (v) => {
-        const [core, pre = ''] = v.split('-', 2);
-        return { n: core.split('.').map((x) => Number(x) || 0), pre: pre ? pre.split('.') : [] };
-    };
-    const x = parse(a);
-    const y = parse(b);
-    for (let i = 0; i < 3; i++)
-        if (x.n[i] !== y.n[i])
-            return x.n[i] > y.n[i];
-    if (!x.pre.length || !y.pre.length)
-        return !x.pre.length && !!y.pre.length;
-    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
-        const p = x.pre[i];
-        const q = y.pre[i];
-        if (p === undefined)
-            return false;
-        if (q === undefined)
-            return true;
-        if (p !== q)
-            return /^\d+$/.test(p) && /^\d+$/.test(q) ? Number(p) > Number(q) : p > q;
-    }
-    return false;
-}
+export { newerVersion };
 /** Grouped report: hub, front door (only when there is one), key, this machine; each problem with a one-line fix. */
 export function formatDoctor(checks) {
     const mark = { ok: '[ok]  ', warn: '[warn]', fail: '[FAIL]', info: '[info]' };

package/dist/src/invite.js

@@ -219,11 +219,11 @@ export function agentInvitePrompt(line, lang = 'en') {
     const spec = /^npx -y (\S+) join /.exec(line)?.[1] ?? npmSpec();
     const npx = `npx -y ${spec}`;
     if (lang === 'zh') {
-        return (`请帮我接入团队的 AgentChannel：在终端运行 \`${line}\`。` +
+        return (`请帮我接入团队的 AgentChannel：在这个项目的目录里运行 \`${line}\`。` +
             `它会保存这个智能体的密钥，并把 AgentChannel 接入你自己，不会安装别的东西；这行只能用一次。` +
             `完成后告诉我收件箱里有什么。如果出错，运行 \`${npx} doctor\`，按提示修好再继续。`);
     }
-    return (`Please connect me to my team's AgentChannel: run \`${line}\` in a terminal. ` +
+    return (`Please connect me to my team's AgentChannel: run \`${line}\` in this project's directory. ` +
         `It stores this agent's key and adds AgentChannel to you; it installs nothing else (the line works once). ` +
         `Then tell me what is in my inbox. If anything fails, run \`${npx} doctor\`, fix what it says, and continue.`);
 }

package/dist/src/mcp.d.ts

@@ -53,10 +53,14 @@ export declare function startSessionNotices(server: McpServer, client: Client, o
     log?: (s: string) => void;
     feed?: Partial<ChangeFeedOptions>;
     gapMs?: number;
+    staleFirstMs?: number;
 }): {
     notifier: AttentionNotifier;
     feed: ChangeFeed;
     done: Promise<void>;
+    stale: {
+        check(): Promise<boolean>;
+    };
     stop(): void;
 } | null;
 export declare function startMcp(client: Client): Promise<void>;

package/dist/src/mcp.js

@@ -8,6 +8,7 @@ import { resolveAttachments, taskFiles } from './attachments.js';
 import { join } from 'node:path';
 import { AttentionNotifier, ChangeFeed, codexQueue, defaultExec, fetchAttention } from './attention.js';
 import { isZh } from './client.js';
+import { startStaleNotice } from './selfupdate.js';
 import { decisionTo, explainToUser } from './names.js';
 export const HANDOFF_TEMPLATE = `## Goal
 <one or two sentences: what done looks like>
@@ -471,13 +472,23 @@ export function startSessionNotices(server, client, o = {}) {
     });
     const feed = new ChangeFeed({ request, socket: () => client.eventsSocket(), onChange: () => notifier.check(), log: o.log, ...o.feed });
     const done = feed.run();
+    // a session cannot be restarted from outside: when the hub names a newer ach, say so once (see selfupdate.ts)
+    const stale = startStaleNotice({
+        fetchVersions: () => client.request('GET', '/api/ach/auth/config'),
+        deliver: sessionDeliverer(server, env, o.exec),
+        lang: isZh(env) ? 'zh' : 'en',
+        firstMs: o.staleFirstMs,
+        log: o.log,
+    });
     return {
         notifier,
         feed,
         done,
+        stale,
         stop() {
             feed.stop();
             notifier.stop();
+            stale.stop();
         },
     };
 }

package/dist/src/runner/runner.d.ts

@@ -15,6 +15,8 @@ export interface RunnerOptions {
     max?: number;
     perm?: Perm;
     intervalMs?: number;
+    /** The hub answered 426 client_too_old: this release is below its floor (the updater checks at once). */
+    onClientTooOld?: () => void;
     heartbeatMs?: number;
     idleMs?: number;
     cfId?: string;
@@ -129,8 +131,11 @@ export declare class Runner {
     me?: Agent;
     private o;
     private stopped;
+    /** quiesce(): the runner takes nothing new (a CLI update is waiting for the runs in flight). */
+    private paused;
     private waiters;
     private lastPrune;
+    private lastTooOld;
     /** Last heartbeat sent for each parked run. */
     private parkedHb;
     /** B7: set when the hub answered 401 (key rotated, agent or owner deactivated): the runner stops. */
@@ -162,6 +167,11 @@ export declare class Runner {
     /** C8: drop runs.json bookkeeping for terminal (or vanished) tasks, every 10 minutes. */
     prune(force?: boolean): Promise<void>;
     pump(): void;
+    /** Stop taking new work and resolve when nothing is queued or running: what a CLI update waits for. Parked runs stay parked (the hub keeps their replies). */
+    quiesce(): Promise<void>;
+    unquiesce(): void;
+    /** Runs in flight plus queued. */
+    busy(): number;
     /** Resolves when nothing is queued or running (tests). */
     drain(): Promise<void>;
     private runJob;

package/dist/src/runner/runner.js

@@ -197,8 +197,11 @@ export class Runner {
     me;
     o;
     stopped = false;
+    /** quiesce(): the runner takes nothing new (a CLI update is waiting for the runs in flight). */
+    paused = false;
     waiters = [];
     lastPrune = 0;
+    lastTooOld = 0;
     /** Last heartbeat sent for each parked run. */
     parkedHb = new Map();
     /** B7: set when the hub answered 401 (key rotated, agent or owner deactivated): the runner stops. */
@@ -280,6 +283,8 @@ export class Runner {
         }
         await this.checkActive();
         await this.prune();
+        if (this.paused)
+            return; // heartbeats of parked runs went out in checkActive; nothing new is taken (it waits in the hub's inbox)
         if (!this.me || inbox.tasks_to_me.length)
             this.me = await this.o.client.me();
         const me = this.me;
@@ -389,6 +394,8 @@ export class Runner {
                     this.parkedHb.set(rec.taskId, now);
                     await this.heartbeat(rec).catch((e) => this.log(`heartbeat ${rec.taskId}: ${e?.message ?? e}`));
                 }
+                if (this.paused)
+                    continue; // quiesced: a parked run resumes after the update (the hub keeps its replies)
                 const me0 = await this.ensureMe();
                 // A new handoff version reaches a parked worker at once, even while it
                 // waits for an answer: the change may settle or replace its question.
@@ -477,6 +484,19 @@ export class Runner {
             });
         }
     }
+    /** Stop taking new work and resolve when nothing is queued or running: what a CLI update waits for. Parked runs stay parked (the hub keeps their replies). */
+    async quiesce() {
+        this.paused = true;
+        await this.drain();
+    }
+    unquiesce() {
+        this.paused = false;
+        this.wake?.();
+    }
+    /** Runs in flight plus queued. */
+    busy() {
+        return this.active.size + this.queue.length;
+    }
     /** Resolves when nothing is queued or running (tests). */
     async drain() {
         if (!this.active.size && !this.queue.length)
@@ -1089,16 +1109,27 @@ export class Runner {
         this.recover();
         this.pump();
         while (!this.stopped) {
+            let wait = this.o.intervalMs;
             try {
                 await this.tick();
             }
             catch (e) {
-                this.log(`poll: ${e?.message ?? e}`);
+                if (e instanceof HubError && e.code === 'client_too_old') {
+                    // the hub refuses this release: poll slowly, say it now and then, and let the updater try at once
+                    wait = Math.max(wait, 30_000);
+                    if (Date.now() - this.lastTooOld > 10 * 60_000) {
+                        this.lastTooOld = Date.now();
+                        this.log(`the hub refuses this ach: ${e.message}`);
+                    }
+                    this.o.onClientTooOld?.();
+                }
+                else
+                    this.log(`poll: ${e?.message ?? e}`);
             }
             if (this.stopped)
                 break;
             await new Promise((r) => {
-                const t = setTimeout(r, this.o.intervalMs);
+                const t = setTimeout(r, wait);
                 this.wake = () => {
                     clearTimeout(t);
                     r();
@@ -1114,6 +1145,7 @@ export class Runner {
     /** Stop polling; abort running jobs without failing their tasks (they resume on restart). */
     async stop() {
         this.stopped = true;
+        this.wake?.(); // start() is asleep between polls: let it end now (a slow poll after a 426 would hold the exit)
         for (const a of this.active.values()) {
             a.reason = a.reason ?? 'stop';
             a.controller.abort();

package/dist/src/selfupdate.d.ts

@@ -0,0 +1,135 @@
+/** A restart-worthy exit: not 0 (systemd on-failure and launchd restart only a failure) and not 78 (key refused: do not restart). */
+export declare const UPDATE_EXIT_CODE = 75;
+export interface HubVersions {
+    latest_client?: string;
+    min_client_proto?: number;
+}
+export type Verdict = {
+    action: 'none';
+}
+/** Safe to install by itself. */
+ | {
+    action: 'update';
+    target: string;
+}
+/** Needs a person: `why` says what to do. */
+ | {
+    action: 'manual';
+    target: string;
+    why: string;
+};
+/** What to do about the release the hub names. Pure: no I/O. */
+export declare function judge(hub: HubVersions | null | undefined, current?: string, proto?: number): Verdict;
+export type ExecFn = (file: string, args: string[], o?: {
+    timeoutMs?: number;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const defaultInstallExec: ExecFn;
+export type InstallKind = 
+/** Started from the npx cache with a range spec (`@koalaauto/agentchannel@3`): a restart fetches the newest release. */
+{
+    kind: 'npx';
+}
+/** A global npm install: `npm install -g`. `dir` is where the package lives. */
+ | {
+    kind: 'global';
+    dir: string;
+}
+/** Source checkout, `npm link`, a project dependency, or anything else: not ours to replace. */
+ | {
+    kind: 'other';
+    why: string;
+};
+/** How this CLI was installed, so that the right update is used (or none). */
+export declare function detectInstall(o?: {
+    self?: string;
+    exec?: ExecFn;
+    version?: string;
+}): Promise<InstallKind>;
+/**
+ * Before the runner stops taking work: the release exists on npm, and a global install can be written. Nothing has been paused or
+ * recorded yet, so a failure here costs nothing and is simply tried again at the next check.
+ */
+export declare function preflight(kind: InstallKind, target: string, exec?: ExecFn): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Install the release. npx needs nothing now (the restart fetches it). A global install is `npm install -g`, scripts off, then read back. */
+export declare function installRelease(kind: InstallKind, target: string, exec?: ExecFn): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+interface UpdateState {
+    target: string;
+    /** ms since epoch of the last attempt. */
+    at: number;
+    attempts: number;
+}
+export declare function loadUpdateState(home: string): UpdateState | null;
+/** The runner as the updater needs it. */
+export interface Quiescable {
+    /** Stop taking new work and resolve when nothing is queued or running. */
+    quiesce(): Promise<void>;
+    /** Take work again (the update did not happen). */
+    unquiesce(): void;
+    /** Runs in flight + queued, for the log. */
+    busy(): number;
+    stop(): Promise<void>;
+}
+export type CheckResult = 'none' | 'manual' | 'off' | 'backoff' | 'busy' | 'failed' | 'restarting';
+export interface SelfUpdaterOptions {
+    fetchVersions: () => Promise<HubVersions | null>;
+    runner: Quiescable;
+    home: string;
+    env?: NodeJS.ProcessEnv;
+    log?: (s: string) => void;
+    exec?: ExecFn;
+    self?: string;
+    version?: string;
+    proto?: number;
+    now?: () => number;
+    /** First check this long after start (default 20 s) and then every 6 h (±10 %). */
+    firstMs?: number;
+    everyMs?: number;
+}
+export declare class SelfUpdater {
+    private o;
+    /** True once the install is done and the runner is stopping: the process should exit UPDATE_EXIT_CODE. */
+    restarting: boolean;
+    private timer?;
+    private stopped;
+    private lastNudge;
+    private working;
+    private told;
+    constructor(o: SelfUpdaterOptions);
+    private log;
+    /** Say a thing once per process (a check every few hours must not repeat itself). */
+    private once;
+    start(): void;
+    stop(): void;
+    /** The hub just refused this release (426): check now, but not more than once in 10 minutes (the runner polls again every 30 s). */
+    nudge(): Promise<CheckResult> | undefined;
+    check(): Promise<CheckResult>;
+}
+export declare function staleText(latest: string, lang?: 'en' | 'zh', current?: string): string;
+/**
+ * One line into the open session when the hub names a newer CLI (once per release per process, checked every 6 h). A session
+ * cannot be restarted from outside, so this is all there is to do for it. Returns stop().
+ */
+export declare function startStaleNotice(o: {
+    fetchVersions: () => Promise<HubVersions | null>;
+    deliver: (text: string) => Promise<boolean>;
+    lang?: 'en' | 'zh';
+    version?: string;
+    proto?: number;
+    firstMs?: number;
+    everyMs?: number;
+    log?: (s: string) => void;
+}): {
+    check(): Promise<boolean>;
+    stop(): void;
+};
+export {};

package/dist/src/selfupdate.js

@@ -0,0 +1,287 @@
+// Keeping a running `ach` current. Two jobs:
+//
+//  - the runner (`ach run`, a long-lived daemon under systemd / launchd): SelfUpdater asks the hub which CLI release is the
+//    newest, and when this one is behind it stops taking new work, waits for the runs in flight, installs the release (a
+//    global install) or relies on npx to fetch it (a service started from the npx cache), and exits with UPDATE_EXIT_CODE.
+//    systemd (Restart=on-failure) and launchd (KeepAlive/SuccessfulExit=false) restart a non-zero exit, so the service comes
+//    back on the new release. Parked runs and queued answers live in the hub and the runner's state file: nothing is lost.
+//  - an MCP session (`ach mcp`, started by Claude Code or Codex): it cannot be restarted from outside, so startStaleNotice
+//    pushes one line into the session saying it is behind.
+//
+// What it never does: move across a major release by itself (the protocol may have changed: a person decides), move a stable
+// install onto a prerelease, touch a CLI it cannot tell how it was installed, or retry a failed update more than once a day.
+// ACH_AUTO_UPDATE=0 turns the installing off (the log and the session notice remain).
+import { execFile } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { thisCliPath } from './invite.js';
+import { CLIENT_PROTO, newerVersion, PKG_NAME, VERSION } from './version.js';
+/** A restart-worthy exit: not 0 (systemd on-failure and launchd restart only a failure) and not 78 (key refused: do not restart). */
+export const UPDATE_EXIT_CODE = 75;
+const DAY_MS = 24 * 3600_000;
+const CHECK_EVERY_MS = 6 * 3600_000;
+const isVersion = (v) => typeof v === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$/.test(v);
+const major = (v) => Number(v.split('.')[0]);
+/** What to do about the release the hub names. Pure: no I/O. */
+export function judge(hub, current = VERSION, proto = CLIENT_PROTO) {
+    const target = hub?.latest_client;
+    const needs = Number(hub?.min_client_proto) > proto;
+    if (!isVersion(target) || !newerVersion(target, current)) {
+        return needs ? { action: 'manual', target: '', why: `the hub needs protocol ${hub.min_client_proto} or newer, but names no newer release: ask the hub's admin` } : { action: 'none' };
+    }
+    if (major(target) !== major(current))
+        return { action: 'manual', target, why: `${target} is a new major release: update it yourself (npm install -g ${PKG_NAME}@${target}), then restart` };
+    if (target.includes('-') && !current.includes('-')) {
+        // the hub runs a prerelease; a stable install stays on stable, unless the hub's floor leaves it no choice (then a person decides)
+        return needs ? { action: 'manual', target, why: `the hub needs protocol ${hub.min_client_proto} or newer and runs the prerelease ${target}: ask the hub's admin for a stable release, or install ${PKG_NAME}@${target} yourself` } : { action: 'none' };
+    }
+    return { action: 'update', target };
+}
+/** `npm` as a service can find it: the one beside this node (a version manager's bin dir is often not in a service's PATH), else PATH's. */
+function resolveBin(file) {
+    if (file !== 'npm')
+        return file;
+    const beside = join(dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(beside) ? beside : file;
+}
+export const defaultInstallExec = (file, args, o) => new Promise((res) => {
+    execFile(resolveBin(file), args, { timeout: o?.timeoutMs ?? 30_000, encoding: 'utf8', maxBuffer: 4 << 20 }, (err, stdout, stderr) => {
+        res({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    });
+});
+const real = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+};
+/** How this CLI was installed, so that the right update is used (or none). */
+export async function detectInstall(o = {}) {
+    const self = real(o.self ?? thisCliPath());
+    if (/[\\/]_npx[\\/]/.test(self)) {
+        // `...@3` re-resolves on a restart; an exact prerelease spec (`...@3.5.0-rc.1`) never moves
+        return (o.version ?? VERSION).includes('-') ? { kind: 'other', why: 'started with npx from an exact prerelease version: run the join line (or `ach run --install-service`) again with the new release' } : { kind: 'npx' };
+    }
+    const exec = o.exec ?? defaultInstallExec;
+    const root = await exec('npm', ['root', '-g']);
+    if (root.code !== 0 || !root.stdout.trim())
+        return { kind: 'other', why: 'npm is not available to update with' };
+    const dir = real(join(root.stdout.trim(), ...PKG_NAME.split('/')));
+    return self === dir || self.startsWith(dir + sep) ? { kind: 'global', dir } : { kind: 'other', why: `${self} is not a global npm install (a checkout, a link or a project dependency)` };
+}
+/**
+ * Before the runner stops taking work: the release exists on npm, and a global install can be written. Nothing has been paused or
+ * recorded yet, so a failure here costs nothing and is simply tried again at the next check.
+ */
+export async function preflight(kind, target, exec = defaultInstallExec) {
+    if (kind.kind === 'other')
+        return { ok: false, detail: kind.why };
+    const v = await exec('npm', ['view', `${PKG_NAME}@${target}`, 'version'], { timeoutMs: 30_000 });
+    if (v.code !== 0 || !v.stdout.split(/\s+/).includes(target))
+        return { ok: false, detail: `${PKG_NAME}@${target} is not on npm (yet), or npm cannot reach it` };
+    if (kind.kind === 'global') {
+        try {
+            accessSync(dirname(kind.dir), constants.W_OK); // <npm root -g>/@koalaauto: where npm replaces the package
+        }
+        catch {
+            return { ok: false, detail: `no permission to write ${dirname(kind.dir)}: run npm install -g ${PKG_NAME}@${target} with the right permissions` };
+        }
+    }
+    return { ok: true, detail: 'ready' };
+}
+/** Install the release. npx needs nothing now (the restart fetches it). A global install is `npm install -g`, scripts off, then read back. */
+export async function installRelease(kind, target, exec = defaultInstallExec) {
+    if (kind.kind === 'other')
+        return { ok: false, detail: kind.why };
+    if (kind.kind === 'npx')
+        return { ok: true, detail: 'npx fetches it on restart' };
+    const r = await exec('npm', ['install', '-g', '--ignore-scripts', '--no-audit', '--no-fund', `${PKG_NAME}@${target}`], { timeoutMs: 5 * 60_000 });
+    if (r.code !== 0)
+        return { ok: false, detail: `npm install -g ${PKG_NAME}@${target} failed (${(r.stderr || r.stdout).trim().split('\n').slice(-3).join(' | ').slice(0, 300)})` };
+    let got = '';
+    try {
+        got = JSON.parse(readFileSync(join(kind.dir, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        /* read below */
+    }
+    return got === target ? { ok: true, detail: `installed ${target}` } : { ok: false, detail: `npm said it installed ${target}, but ${kind.dir} has ${got || 'no package.json'}` };
+}
+const stateFile = (home) => join(home, 'update.json');
+export function loadUpdateState(home) {
+    try {
+        const s = JSON.parse(readFileSync(stateFile(home), 'utf8'));
+        return isVersion(s?.target) && Number.isFinite(s?.at) ? { target: s.target, at: s.at, attempts: Number(s.attempts) || 1 } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveUpdateState(home, s) {
+    try {
+        if (!existsSync(home))
+            mkdirSync(home, { recursive: true, mode: 0o700 });
+        writeFileSync(stateFile(home), s ? JSON.stringify(s) : '{}', { mode: 0o600 });
+    }
+    catch {
+        /* the back-off is a courtesy; a read-only home just means a retry sooner */
+    }
+}
+export class SelfUpdater {
+    o;
+    /** True once the install is done and the runner is stopping: the process should exit UPDATE_EXIT_CODE. */
+    restarting = false;
+    timer;
+    stopped = false;
+    lastNudge = 0;
+    working = false;
+    told = new Set();
+    constructor(o) {
+        this.o = o;
+    }
+    log(s) {
+        (this.o.log ?? ((x) => console.error(x)))(`[ach update] ${s}`);
+    }
+    /** Say a thing once per process (a check every few hours must not repeat itself). */
+    once(key, s) {
+        if (this.told.has(key))
+            return;
+        this.told.add(key);
+        this.log(s);
+    }
+    start() {
+        const every = this.o.everyMs ?? CHECK_EVERY_MS;
+        const next = (ms) => {
+            if (this.stopped)
+                return;
+            this.timer = setTimeout(() => void this.check().finally(() => next(every * (0.9 + Math.random() * 0.2))), ms);
+            this.timer.unref?.();
+        };
+        next(this.o.firstMs ?? 20_000);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    /** The hub just refused this release (426): check now, but not more than once in 10 minutes (the runner polls again every 30 s). */
+    nudge() {
+        const now = (this.o.now ?? Date.now)();
+        if (this.stopped || now - this.lastNudge < 10 * 60_000)
+            return undefined;
+        this.lastNudge = now;
+        return this.check();
+    }
+    async check() {
+        if (this.working || this.restarting)
+            return 'busy';
+        const version = this.o.version ?? VERSION;
+        const now = (this.o.now ?? Date.now)();
+        let hub = null;
+        try {
+            hub = await this.o.fetchVersions();
+        }
+        catch {
+            return 'none'; // offline or an old hub: nothing to act on
+        }
+        const prior = loadUpdateState(this.o.home);
+        if (prior && prior.target === version)
+            saveUpdateState(this.o.home, null); // it worked: forget the back-off
+        const v = judge(hub, version, this.o.proto);
+        if (v.action === 'none')
+            return 'none';
+        if (v.action === 'manual') {
+            this.once(`manual:${v.target}`, `${v.why}`);
+            return 'manual';
+        }
+        if ((this.o.env ?? process.env).ACH_AUTO_UPDATE === '0') {
+            this.once(`off:${v.target}`, `ach ${v.target} is out (this is ${version}); ACH_AUTO_UPDATE=0, so it is not installed: npm install -g ${PKG_NAME}@${v.target}`);
+            return 'off';
+        }
+        // an attempt that did not end on this release (npx served a cached one, npm refused) is not repeated for a day
+        const last = prior && prior.target === v.target ? prior : null;
+        if (last && now - last.at < DAY_MS) {
+            this.once(`backoff:${v.target}`, `ach ${v.target} is out but the last try ${new Date(last.at).toISOString()} did not end on it; trying again after a day`);
+            return 'backoff';
+        }
+        const kind = await detectInstall({ self: this.o.self, exec: this.o.exec, version });
+        if (kind.kind === 'other') {
+            this.once(`other:${v.target}`, `ach ${v.target} is out (this is ${version}) and cannot be installed by itself: ${kind.why}`);
+            return 'manual';
+        }
+        const ready = await preflight(kind, v.target, this.o.exec);
+        if (!ready.ok) {
+            this.once(`preflight:${v.target}`, `ach ${v.target} is out (this is ${version}) but cannot be installed now: ${ready.detail}; nothing was paused, trying again later`);
+            return 'failed';
+        }
+        this.working = true;
+        try {
+            this.log(`ach ${v.target} is out (this is ${version}): taking no new work, ${this.o.runner.busy()} run(s) to finish first`);
+            await this.o.runner.quiesce();
+            saveUpdateState(this.o.home, { target: v.target, at: now, attempts: (last?.attempts ?? 0) + 1 });
+            const r = await installRelease(kind, v.target, this.o.exec);
+            if (!r.ok) {
+                this.log(`update to ${v.target} failed: ${r.detail}; staying on ${version}`);
+                this.o.runner.unquiesce();
+                return 'failed';
+            }
+            this.log(`${r.detail}; restarting into ${v.target}`);
+            this.restarting = true;
+            await this.o.runner.stop();
+            return 'restarting';
+        }
+        finally {
+            this.working = false;
+        }
+    }
+}
+// ---- the MCP session -------------------------------------------------------------------------------------------------------
+export function staleText(latest, lang = 'en', current = VERSION) {
+    return lang === 'zh'
+        ? `AgentChannel：本机的 ach ${current} 已过期（你的 hub 是 ${latest}）。请告诉你的用户：重启这个会话；若 ach 是全局安装的，先运行 npm install -g ${PKG_NAME}@${latest}`
+        : `AgentChannel: the ach in this session is ${current}, out of date (your hub is on ${latest}). Tell your user to restart this session; if ach is installed globally, first run: npm install -g ${PKG_NAME}@${latest}`;
+}
+/**
+ * One line into the open session when the hub names a newer CLI (once per release per process, checked every 6 h). A session
+ * cannot be restarted from outside, so this is all there is to do for it. Returns stop().
+ */
+export function startStaleNotice(o) {
+    const told = new Set();
+    let timer;
+    let stopped = false;
+    const check = async () => {
+        try {
+            const hub = await o.fetchVersions();
+            const v = judge(hub, o.version, o.proto);
+            const target = v.action === 'none' ? '' : v.target || (hub?.latest_client ?? '');
+            if (!target || told.has(target))
+                return false;
+            const ok = await o.deliver(staleText(target, o.lang, o.version));
+            if (ok)
+                told.add(target);
+            return ok;
+        }
+        catch (e) {
+            o.log?.(`stale check: ${e?.message ?? e}`);
+            return false;
+        }
+    };
+    const next = (ms) => {
+        if (stopped)
+            return;
+        timer = setTimeout(() => void check().finally(() => next((o.everyMs ?? CHECK_EVERY_MS) * (0.9 + Math.random() * 0.2))), ms);
+        timer.unref?.();
+    };
+    next(o.firstMs ?? 15_000);
+    return {
+        check,
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}

package/dist/src/version.d.ts

@@ -1,3 +1,11 @@
-export declare const VERSION = "3.4.0";
+export declare const VERSION = "3.6.0";
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export declare const PKG_NAME = "@koalaauto/agentchannel";
+/**
+ * What this CLI says about itself on every request (x-ach-proto). The hub's ACH_MIN_CLIENT_PROTO refuses a CLI below its
+ * floor. Raise this only when the CLI starts to need something an older hub does not have, and a hub only when it can no
+ * longer serve the older CLIs: docs/api/README.md, "Client compatibility". 1 = the CLI announces itself (3.5).
+ */
+export declare const CLIENT_PROTO = 1;
+/** True when version a is newer than b (x.y.z, a release beats its own prereleases; prerelease parts compared by number when numeric). */
+export declare function newerVersion(a: string, b: string): boolean;

package/dist/src/version.js

@@ -1,3 +1,34 @@
-export const VERSION = '3.4.0';
+export const VERSION = '3.6.0';
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export const PKG_NAME = '@koalaauto/agentchannel';
+/**
+ * What this CLI says about itself on every request (x-ach-proto). The hub's ACH_MIN_CLIENT_PROTO refuses a CLI below its
+ * floor. Raise this only when the CLI starts to need something an older hub does not have, and a hub only when it can no
+ * longer serve the older CLIs: docs/api/README.md, "Client compatibility". 1 = the CLI announces itself (3.5).
+ */
+export const CLIENT_PROTO = 1;
+/** True when version a is newer than b (x.y.z, a release beats its own prereleases; prerelease parts compared by number when numeric). */
+export function newerVersion(a, b) {
+    const parse = (v) => {
+        const [core, pre = ''] = v.split('-', 2);
+        return { n: core.split('.').map((x) => Number(x) || 0), pre: pre ? pre.split('.') : [] };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < 3; i++)
+        if (x.n[i] !== y.n[i])
+            return x.n[i] > y.n[i];
+    if (!x.pre.length || !y.pre.length)
+        return !x.pre.length && !!y.pre.length;
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === undefined)
+            return false;
+        if (q === undefined)
+            return true;
+        if (p !== q)
+            return /^\d+$/.test(p) && /^\d+$/.test(q) ? Number(p) > Number(q) : p > q;
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalaauto/agentchannel",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Hand work between your team's agents (Claude Code, Codex) and follow it in one panel: the ach CLI, MCP server and runner for AgentChannel v2",
   "keywords": [
     "agentchannel",