@koalaauto/agentchannel 3.2.0 → 3.4.0

package/README.md

@@ -40,8 +40,8 @@ installed or changed.
   pasting the line was the consent, so it does the same and says what it ran.
 - `--service` also installs the background helper (`ach run --install-service
   --interactive-first` for the current directory; `--notify` only on a machine
-  with a desktop). Through npx it first installs this version globally, since a
-  service cannot run from the npx cache.
+  with a desktop), and starts it. Through npx the service runs the same pinned
+  npx spec as the MCP entry, so nothing is installed globally.
 - `--dry-run` prints the plan; the invite is not used and nothing is written.
 - `--yes` skips the question.
 
@@ -92,7 +92,8 @@ reminds you with one line, never the message itself:
   `codex queue --thread <session> --message "<the line>"` when Codex tells it
   the session id (`CODEX_THREAD_ID`; or set `ACH_CODEX_THREAD_ID`). Otherwise
   it does nothing and the desktop notification covers it.
-- **Desktop** (`ach run --notify`, on by default with `--install-service`):
+- **Desktop** (`ach run --notify`, on by default with `--install-service` on a
+  machine with a desktop):
   an OS notification. Decision requests show their options as buttons where
   the OS can report the click: macOS with
   [`alerter`](https://github.com/vjeantet/alerter) installed (else

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, off otherwise)\n            ach run --install-service [same flags]   (writes a launchd/systemd user unit; does not load it)\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> [--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 {};

package/dist/src/args.js

@@ -202,8 +202,8 @@ Runner:     ach run --dir <path> [--repo name=path ...] [--runtime claude|codex]
                     [--perm read|workdir|full] [--model m] [--pass-env NAME ...]
                     [--claim-delay <sec> | --interactive-first]   (default 0; --interactive-first = 600 s for you to claim first)
                     [--notify | --no-notify]   (desktop notifications for your owner's important / needs-you items;
-                     default on for --install-service, off otherwise)
-            ach run --install-service [same flags]   (writes a launchd/systemd user unit; does not load it)
+                     default on for --install-service where there is a desktop, off otherwise)
+            ach run --install-service [same flags]   (installs and starts a launchd/systemd user unit; runs at login)
             ach run --gc [--dir <path>] [--days 7]
 MCP:        ach mcp   (stdio server; your interactive agent can also claim and work tasks)
 Panel:      ach open [--print]   (opens the panel in your browser, logged in as this agent's owner; 60 s single-use link)

package/dist/src/attention.d.ts

@@ -46,31 +46,59 @@ export declare class AttentionNotifier {
     private run;
     stop(): void;
 }
+/** What ChangeFeed needs of a WebSocket (the WHATWG interface: undici's, a browser's, a test's fake). */
+export interface FeedSocket {
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', fn: (ev: any) => void): void;
+    close(code?: number, reason?: string): void;
+}
 export interface ChangeFeedOptions {
     request: Request;
     onChange: () => unknown;
+    /** Opens the hub's change stream (GET /api/ach/events; Client.eventsSocket). Absent or null: long poll only. */
+    socket?: () => FeedSocket | null;
+    /** How long a socket may take to open before the long poll takes over. */
+    wsOpenMs?: number;
+    /** While on the socket, check anyway this often (a change that published no event, a socket that died silently). */
+    wsCheckMs?: number;
     /** Long-poll wait (s), ≤ 25. */
     waitS?: number;
     /** Fallback polling interval. */
     pollMs?: number;
+    /** In polling mode, try the socket again after this many polls (a hub that was down at start). */
+    wsRetryPolls?: number;
     sleep?: (ms: number) => Promise<void>;
     log?: (s: string) => void;
 }
 /**
- * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
- * every pollMs) when the hub refuses the route (403/404: an older hub, or
- * person sessions only) — permanently — or after an error (one interval, then
- * the long poll again).
+ * Follows the hub's changes, with fallbacks, like the panel (hub/pb_public/realtime.js):
+ *   1. the WebSocket GET /api/ach/events (the Worker hub): "something changed", ids only; a socket that worked and
+ *      then closed (a deploy, a network change) is opened again;
+ *   2. when it does not open, the long poll GET /api/ach/changes (the PocketBase hub);
+ *   3. when the hub refuses that (403/404/405), polling (onChange every pollMs); from there the socket is tried again
+ *      now and then. An error on the long poll: one polling interval, then the long poll again.
+ * onChange calls never overlap: a change during one runs it once more afterwards.
  */
 export declare class ChangeFeed {
     private o;
-    mode: 'longpoll' | 'poll';
+    mode: 'ws' | 'longpoll' | 'poll';
     private stopped;
     private cursor;
+    private ws;
+    /** Ends the socket being followed now (stop() does not wait for the closing handshake). */
+    private endSocket;
+    private wsDue;
+    /** The socket opened at least once (a later failure retries it before giving up). */
+    private wsWorked;
+    private firing;
+    private again;
     constructor(o: ChangeFeedOptions);
     stop(): void;
     private fire;
-    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    /** One socket, until it ends. Resolves with how long it was open (ms), or -1 when it never opened. */
+    private oneSocket;
+    /** Stays on the socket while it works; returns when it cannot be used (or on stop). */
+    private followSocket;
+    /** Runs until stop(). `rounds` bounds the long-poll / polling loop (tests). */
     run(rounds?: number): Promise<void>;
 }
 export type Exec = (cmd: string, args: string[]) => Promise<{

package/dist/src/attention.js

@@ -2,9 +2,9 @@
  * Reminders, never content. Two pieces shared by `ach mcp` (an open Claude
  * Code / Codex session) and `ach run --notify` (the background helper):
  *
- * - ChangeFeed: follows the hub's change stream. GET /api/ach/changes long-poll
- *   (wait ≈ 25 s); when the hub refuses it (older hub: person sessions only) or
- *   it errors, falls back to polling every 15 s.
+ * - ChangeFeed: follows the hub's change stream: the GET /api/ach/events
+ *   WebSocket (the Worker hub), else the GET /api/ach/changes long poll
+ *   (wait ≈ 25 s; the PocketBase hub), else polling every 15 s.
  * - AttentionNotifier: on a change, counts what needs the owner (questions,
  *   decisions, mentions...) and, when something new arrived, delivers ONE line
  *   ("AgentChannel: 2 items need you (1 question, 1 decision) — say 'check my
@@ -171,40 +171,183 @@ export class AttentionNotifier {
 }
 const realSleep = (ms) => new Promise((r) => setTimeout(r, ms).unref?.());
 /**
- * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
- * every pollMs) when the hub refuses the route (403/404: an older hub, or
- * person sessions only) — permanently — or after an error (one interval, then
- * the long poll again).
+ * Follows the hub's changes, with fallbacks, like the panel (hub/pb_public/realtime.js):
+ *   1. the WebSocket GET /api/ach/events (the Worker hub): "something changed", ids only; a socket that worked and
+ *      then closed (a deploy, a network change) is opened again;
+ *   2. when it does not open, the long poll GET /api/ach/changes (the PocketBase hub);
+ *   3. when the hub refuses that (403/404/405), polling (onChange every pollMs); from there the socket is tried again
+ *      now and then. An error on the long poll: one polling interval, then the long poll again.
+ * onChange calls never overlap: a change during one runs it once more afterwards.
  */
 export class ChangeFeed {
     o;
     mode = 'longpoll';
     stopped = false;
     cursor = '';
+    ws = null;
+    /** Ends the socket being followed now (stop() does not wait for the closing handshake). */
+    endSocket = null;
+    wsDue;
+    /** The socket opened at least once (a later failure retries it before giving up). */
+    wsWorked = false;
+    firing = null;
+    again = false;
     constructor(o) {
         this.o = o;
+        this.wsDue = !!o.socket;
     }
     stop() {
         this.stopped = true;
-    }
-    async fire() {
+        const s = this.ws;
+        this.ws = null;
         try {
-            await this.o.onChange();
+            s?.close(1000, 'bye');
         }
         catch {
-            /* the consumer logs its own errors */
+            /* already closed */
         }
+        this.endSocket?.();
     }
-    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    fire() {
+        if (this.firing) {
+            this.again = true;
+            return this.firing;
+        }
+        this.firing = (async () => {
+            do {
+                this.again = false;
+                try {
+                    await this.o.onChange();
+                }
+                catch {
+                    /* the consumer logs its own errors */
+                }
+            } while (this.again && !this.stopped);
+        })().finally(() => {
+            this.firing = null;
+        });
+        return this.firing;
+    }
+    /** One socket, until it ends. Resolves with how long it was open (ms), or -1 when it never opened. */
+    oneSocket() {
+        return new Promise((resolve) => {
+            let s = null;
+            try {
+                s = this.o.socket();
+            }
+            catch (e) {
+                this.o.log?.(`change stream: socket: ${String(e?.message ?? e).slice(0, 200)}`);
+            }
+            if (!s)
+                return resolve(-1);
+            const sock = s;
+            this.ws = sock;
+            let openedAt = 0;
+            let done = false;
+            let check = null;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(openTimer);
+                if (check)
+                    clearInterval(check);
+                if (this.ws === sock)
+                    this.ws = null;
+                this.endSocket = null;
+                resolve(openedAt ? Date.now() - openedAt : -1);
+            };
+            this.endSocket = finish;
+            const openTimer = setTimeout(() => {
+                if (openedAt)
+                    return;
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                finish();
+            }, this.o.wsOpenMs ?? 5000);
+            openTimer.unref?.();
+            sock.addEventListener('open', () => {
+                if (done)
+                    return;
+                openedAt = Date.now();
+                clearTimeout(openTimer);
+                if (this.mode !== 'ws')
+                    this.o.log?.('change stream: connected (websocket)');
+                this.mode = 'ws';
+                this.wsWorked = true;
+                void this.fire();
+                check = setInterval(() => void this.fire(), this.o.wsCheckMs ?? 5 * 60_000);
+                check.unref?.();
+            });
+            sock.addEventListener('message', () => {
+                if (!done && !this.stopped)
+                    void this.fire();
+            });
+            sock.addEventListener('close', finish);
+            sock.addEventListener('error', () => {
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                finish();
+            });
+        });
+    }
+    /** Stays on the socket while it works; returns when it cannot be used (or on stop). */
+    async followSocket(sleep) {
+        let fails = 0;
+        while (!this.stopped) {
+            const lived = await this.oneSocket();
+            if (this.stopped)
+                return;
+            // a socket that stayed up a while worked: open it again at once; one that dropped quickly counts as a failure
+            if (lived >= 10_000)
+                fails = 0;
+            else
+                fails++;
+            if (!this.wsWorked || fails >= 4)
+                return;
+            if (fails > 0)
+                this.o.log?.('change stream: socket closed; reconnecting');
+            await sleep(Math.min(30_000, 1000 * 2 ** Math.max(0, fails - 1)));
+        }
+    }
+    /** Runs until stop(). `rounds` bounds the long-poll / polling loop (tests). */
     async run(rounds = Infinity) {
         const sleep = this.o.sleep ?? realSleep;
         const poll = this.o.pollMs ?? 15_000;
         const wait = Math.min(25, this.o.waitS ?? 25);
+        const retryPolls = this.o.wsRetryPolls ?? 20;
         let errors = 0;
-        for (let i = 0; i < rounds && !this.stopped; i++) {
+        let polls = 0;
+        let longpollRefused = false;
+        for (let i = 0; i < rounds && !this.stopped;) {
+            if (this.wsDue) {
+                this.wsDue = false;
+                await this.followSocket(sleep);
+                if (this.stopped)
+                    return;
+                const was = this.mode;
+                this.mode = longpollRefused ? 'poll' : 'longpoll';
+                this.cursor = '';
+                if (was === 'ws')
+                    this.o.log?.(`change stream: websocket lost; ${this.mode === 'poll' ? `polling every ${Math.round(poll / 1000)} s` : 'long poll'}`);
+                continue;
+            }
+            i++;
             if (this.mode === 'poll') {
                 await this.fire();
                 await sleep(poll);
+                if (this.o.socket && ++polls >= retryPolls) {
+                    polls = 0;
+                    this.wsDue = true;
+                }
                 continue;
             }
             const t0 = Date.now();
@@ -226,6 +369,7 @@ export class ChangeFeed {
             catch (e) {
                 if (e instanceof HubError && (e.status === 403 || e.status === 404 || e.status === 405)) {
                     this.mode = 'poll';
+                    longpollRefused = true;
                     this.o.log?.(`change stream not available (${e.status}); polling every ${Math.round(poll / 1000)} s`);
                     continue;
                 }

package/dist/src/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { chmodSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { delimiter, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { HELP, parseCli, UsageError } from './args.js';
 import { channelRef, Client, clientFromConfig, HubError, isZh, parseLinkRepo } from './client.js';
@@ -1691,7 +1692,7 @@ async function runCommand(p, io) {
     let desk = null;
     if (v.notify && !v['no-notify']) {
         const { DeskNotifier } = await import('./desknotify.js');
-        const dn = new DeskNotifier({ request: (m, path) => c.request(m, path), home, hub: env.ACH_PUBLIC_URL || cfg.hub, env, log: io.err });
+        const dn = new DeskNotifier({ request: (m, path) => c.request(m, path), socket: () => c.eventsSocket(), home, hub: env.ACH_PUBLIC_URL || cfg.hub, env, log: io.err });
         dn.start();
         desk = dn;
         io.err('ach run: desktop notifications on (--no-notify to turn off)');
@@ -1748,12 +1749,15 @@ export const AUTH_EXIT_CODE = 78;
 export const AUTH_EXIT_MESSAGE = 'ach run: key rotated or agent deactivated — run ach join';
 /**
  * P4: write a launchd plist (macOS) or systemd user unit (Linux) that runs this
- * runner with the same flags. Writes the file and prints how to start it; it
- * never loads the unit. ACH_SERVICE_DIR / ACH_SERVICE_PLATFORM override the
- * location and platform (tests).
+ * runner with the same flags, and load it: it runs now and at every login.
+ * From the npx cache the unit runs `npx -y <spec>` (the cache may be cleared;
+ * the MCP entry does the same). ACH_SERVICE_DIR / ACH_SERVICE_PLATFORM override
+ * the location and platform (tests); with ACH_SERVICE_DIR nothing is loaded.
  */
 async function installService(p, io, o) {
     const { serviceFile, writeServiceFile } = await import('./service.js');
+    const { hasDesktop } = await import('./onboard.js');
+    const { isBundledBin, npmSpec, whichAll } = await import('./invite.js');
     const env = io.env;
     const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
     if (platform !== 'darwin' && platform !== 'linux')
@@ -1767,13 +1771,15 @@ async function installService(p, io, o) {
             args.push(`--${f}`, str(v[f]));
     if (v['interactive-first'])
         args.push('--interactive-first');
-    // a service runs in the background: desktop notifications are on unless --no-notify
-    if (!v['no-notify'])
+    // a service runs in the background: desktop notifications where there is a desktop, unless --no-notify
+    if (v.notify || (!v['no-notify'] && hasDesktop(env, platform)))
         args.push('--notify');
     const passEnv = (Array.isArray(v['pass-env']) ? v['pass-env'] : []).flatMap(splitList);
     for (const n of passEnv)
         args.push('--pass-env', n);
-    const svcEnv = { PATH: env.PATH ?? '/usr/bin:/bin' };
+    // not the npx cache's bin dirs: they vanish when npm clears the cache, and hold bundled tools (a codex) that are not the user's
+    const path = (env.PATH ?? '').split(delimiter).filter((d) => d && !isBundledBin(join(d, 'x'))).join(delimiter);
+    const svcEnv = { PATH: path || '/usr/bin:/bin' };
     if (env.AGENTCHANNEL_HOME)
         svcEnv.AGENTCHANNEL_HOME = env.AGENTCHANNEL_HOME;
     if (env.ACH_KEYSTORE)
@@ -1783,30 +1789,55 @@ async function installService(p, io, o) {
     if (platform === 'darwin')
         svcEnv.ACH_AUTH_EXIT_CODE = '0';
     mkdirSync(join(o.home, 'logs'), { recursive: true, mode: 0o700 });
+    const self = fileURLToPath(import.meta.url);
+    const npx = /[\\/]_npx[\\/]/.test(self) ? (whichAll('npx', env).find((x) => !isBundledBin(x)) ?? join(dirname(process.execPath), 'npx')) : undefined;
     const f = serviceFile({
         platform,
         agentName: o.agentName,
-        node: process.execPath,
-        cli: fileURLToPath(import.meta.url),
+        command: npx ? [npx, '-y', npmSpec()] : [process.execPath, self],
         args,
         env: svcEnv,
         logFile: join(o.home, 'logs', 'runner.log'),
     }, env.ACH_SERVICE_DIR || undefined);
     writeServiceFile(f);
+    const load = !env.ACH_SERVICE_DIR;
+    let failed = '';
+    if (load) {
+        for (const c of f.start) {
+            try {
+                execFileSync('/bin/sh', ['-c', c], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+            }
+            catch (e) {
+                failed = `${c}: ${String(e?.stderr ?? e?.message ?? e).trim().split('\n')[0]}`;
+                break;
+            }
+        }
+    }
+    // Linux: a user unit stops at logout (an SSH session ending) unless the user lingers
+    const linger = platform === 'linux' && load && !failed ? lingers(env) : true;
+    const logs = platform === 'linux' ? `journalctl --user -u ${basename(f.path)} -f` : join(o.home, 'logs', 'runner.log');
     if (v.json) {
-        io.out(JSON.stringify({ path: f.path, start: f.start, stop: f.stop }, null, 2));
-        return 0;
+        io.out(JSON.stringify({ path: f.path, started: load && !failed, ...(failed ? { error: failed } : {}), start: f.start, stop: f.stop }, null, 2));
+        return failed ? 1 : 0;
     }
     io.out([
-        `wrote ${f.path} (not loaded)`,
-        'Start it with:',
-        ...f.start.map((x) => `  ${x}`),
-        'Stop it with:',
-        ...f.stop.map((x) => `  ${x}`),
-        `Runner output: ${join(o.home, 'logs', 'runner.log')}`,
+        !load ? `wrote ${f.path} (not loaded: ACH_SERVICE_DIR is set). Start it with:` : failed ? `wrote ${f.path}, but starting it failed: ${failed}\nStart it with:` : `installed and started ${f.path} (also starts at login)`,
+        ...(!load || failed ? f.start.map((x) => `  ${x}`) : []),
+        `Stop it with: ${f.stop.join(' && ')}`,
+        `Runner output: ${logs}`,
+        ...(linger ? [] : ['Note: it stops when you log out of this machine. To keep it running: sudo loginctl enable-linger "$USER"']),
         ...(passEnv.length ? [`Note: the unit passes --pass-env ${passEnv.join(',')} but not their values; add them to the unit's environment yourself.`] : []),
     ].join('\n'));
-    return 0;
+    return failed ? 1 : 0;
+}
+/** Linux: does this user's systemd outlive their logins (loginctl linger)? Unknown counts as yes (no false alarm). */
+function lingers(env) {
+    try {
+        return execFileSync('loginctl', ['show-user', env.USER || String(process.getuid?.() ?? ''), '-p', 'Linger', '--value'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() !== 'no';
+    }
+    catch {
+        return true;
+    }
 }
 function isEntry() {
     try {

package/dist/src/client.d.ts

@@ -303,6 +303,13 @@ export declare class Client {
     private cfSecret?;
     private fetchFn;
     constructor(o: ClientOptions);
+    private ownFetch;
+    /**
+     * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
+     * travels as the `ach.<token>` subprotocol; the Cloudflare Access service token as headers, like every request.
+     * null without a token, or when this client was given its own fetch (a socket would bypass it).
+     */
+    eventsSocket(): WebSocket | null;
     headers(json?: boolean): Record<string, string>;
     /** `files`: local paths (already checked by resolveAttachments) sent as multipart with the JSON in field "json". */
     request<T = any>(method: string, path: string, body?: unknown, files?: string[]): Promise<T>;

package/dist/src/client.js

@@ -1,5 +1,6 @@
 import { openAsBlob, statSync } from 'node:fs';
 import { basename } from 'node:path';
+import { WebSocket as UndiciWebSocket } from 'undici';
 import { attachmentForm, bigFiles, downloadFile, isLinkRef, linkRef, taskFiles, typeOf, uploadTarget } from './attachments.js';
 export const TERMINAL = ['completed', 'failed', 'canceled'];
 export function isTerminal(s) {
@@ -69,6 +70,25 @@ export class Client {
         this.cfId = o.cfId;
         this.cfSecret = o.cfSecret;
         this.fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
+        this.ownFetch = !!o.fetch;
+    }
+    ownFetch;
+    /**
+     * The hub's change stream (GET /api/ach/events, a WebSocket that says "something changed", ids only). The token
+     * travels as the `ach.<token>` subprotocol; the Cloudflare Access service token as headers, like every request.
+     * null without a token, or when this client was given its own fetch (a socket would bypass it).
+     */
+    eventsSocket() {
+        if (!this.token || this.ownFetch)
+            return null;
+        const url = new URL('/api/ach/events', `${this.hub}/`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        const headers = { 'user-agent': 'agentchannel-cli' };
+        if (this.cfId && this.cfSecret) {
+            headers['CF-Access-Client-Id'] = this.cfId;
+            headers['CF-Access-Client-Secret'] = this.cfSecret;
+        }
+        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' };

package/dist/src/desknotify.d.ts

@@ -60,6 +60,8 @@ export interface DeskNotifierOptions {
     /** Runs a notifier that waits for the click (alerter, notify-send --wait): long timeout. */
     actionExec?: NotifyExec;
     log?: (s: string) => void;
+    /** Opens the hub's change stream (Client.eventsSocket); absent: long poll, then polling. */
+    socket?: () => import('./attention.js').FeedSocket | null;
 }
 /** A decision notification waits up to an hour for the click. */
 export declare const ACTION_TIMEOUT_S = 3600;
@@ -123,6 +125,8 @@ export declare class DeskNotifier {
     private baseline;
     private timer;
     private busy;
+    /** The hub has no notification list (404): stop asking, say so once. */
+    private off;
     private feed;
     private linuxActions?;
     /** Click handlers still waiting (tests await them). */
@@ -147,7 +151,7 @@ export declare class DeskNotifier {
      * handled in the background: the notifier keeps polling meanwhile.
      */
     private showActions;
-    /** Follows the hub's change stream (long poll; 15 s polling fallback). */
+    /** Follows the hub's change stream (WebSocket, else long poll, else 15 s polling). */
     start(): void;
     private stopped;
     stop(): void;

package/dist/src/desknotify.js

@@ -242,6 +242,8 @@ export class DeskNotifier {
     baseline;
     timer = null;
     busy = false;
+    /** The hub has no notification list (404): stop asking, say so once. */
+    off = false;
     feed = null;
     linuxActions;
     /** Click handlers still waiting (tests await them). */
@@ -286,7 +288,7 @@ export class DeskNotifier {
     }
     /** One poll: show new alert items (oldest first). Returns how many were shown. */
     async tick() {
-        if (this.busy)
+        if (this.busy || this.off)
             return 0;
         this.busy = true;
         try {
@@ -325,6 +327,11 @@ export class DeskNotifier {
             return shown;
         }
         catch (e) {
+            if (e?.status === 404) {
+                this.off = true;
+                this.o.log?.('ach run --notify: this hub has no notification list; desktop notifications are off');
+                return 0;
+            }
             this.o.log?.(`ach run --notify: ${oneLine(e?.message ?? e, 200)}`);
             return 0;
         }
@@ -404,12 +411,12 @@ export class DeskNotifier {
         });
         return true;
     }
-    /** Follows the hub's change stream (long poll; 15 s polling fallback). */
+    /** Follows the hub's change stream (WebSocket, else long poll, else 15 s polling). */
     start() {
         void import('./attention.js').then(({ ChangeFeed }) => {
             if (this.stopped)
                 return;
-            const feed = new ChangeFeed({ request: (m, p) => this.o.request(m, p), onChange: () => this.tick(), pollMs: this.o.intervalMs, log: this.o.log });
+            const feed = new ChangeFeed({ request: (m, p) => this.o.request(m, p), socket: this.o.socket, onChange: () => this.tick(), pollMs: this.o.intervalMs, log: this.o.log });
             this.feed = feed;
             void feed.run();
         });

package/dist/src/doctor.js

@@ -206,7 +206,7 @@ export async function runDoctor(o) {
     const self = o.self ?? thisCliPath();
     const achs = whichAll('ach', env).map((p) => identifyAch(p, self));
     if (!achs.length) {
-        add('ach on PATH', 'warn', 'no `ach` command on PATH', 'machine', `npm install -g ${npmSpec()} (needed only to type \`ach\` yourself or for the background helper: the join line with --service does it)`);
+        add('ach on PATH', 'warn', 'no `ach` command on PATH', 'machine', `npm install -g ${npmSpec()} (needed only to type \`ach\` yourself)`);
     }
     else {
         const desc = (a) => `${a.path}${a.real && a.real !== a.path ? ` -> ${a.real}` : ''} (${a.ours ? 'this CLI' : `${a.name ?? 'unknown'} ${a.version ?? ''}`.trim()})`;
@@ -220,17 +220,26 @@ export async function runDoctor(o) {
         for (const a of achs.slice(1))
             add('ach (shadowed)', isOurs(a) ? 'info' : 'warn', desc(a));
     }
-    if (/[\\/]_npx[\\/]/.test(self)) {
-        add('install', 'warn', 'this `ach` runs from the npx cache, which npm may clear', 'machine', `npm install -g ${npmSpec()}`);
-    }
-    // Background runner (ach run --install-service): is a unit file there?
+    // Background runner (ach run --install-service): installed, and running?
     if (agentName) {
         try {
-            const { serviceFile } = await import('./service.js');
+            const { serviceFile, serviceLabel } = await import('./service.js');
             const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
             if (platform === 'darwin' || platform === 'linux') {
-                const f = serviceFile({ platform, agentName, node: '', cli: '', args: [], env: {}, logFile: '' }, env.ACH_SERVICE_DIR || undefined);
-                add('background', 'info', existsSync(f.path) ? `tasks are picked up in the background (${f.path})` : 'no background runner on this machine (optional: ach run --dir <repo> --install-service --interactive-first)');
+                const f = serviceFile({ platform, agentName, command: [], args: [], env: {}, logFile: '' }, env.ACH_SERVICE_DIR || undefined);
+                if (!existsSync(f.path))
+                    add('background', 'info', 'no background runner on this machine (optional: ach run --dir <repo> --install-service --interactive-first)');
+                else {
+                    const unit = f.path.split(/[\\/]/).pop();
+                    const r = platform === 'linux'
+                        ? await exec('systemctl', ['--user', 'is-active', unit], env)
+                        : await exec('launchctl', ['print', `gui/${process.getuid?.() ?? ''}/${serviceLabel(agentName)}`], env);
+                    const running = platform === 'linux' ? r.stdout.trim() === 'active' : r.code === 0 && /state = running/.test(r.stdout);
+                    if (running)
+                        add('background', 'ok', `tasks are picked up in the background (${f.path})`);
+                    else
+                        add('background', 'warn', `the background runner is installed but not running (${f.path})`, 'machine', f.start.join(' && '));
+                }
             }
         }
         catch {

package/dist/src/mcp.js

@@ -469,7 +469,7 @@ export function startSessionNotices(server, client, o = {}) {
         gapMs: o.gapMs,
         log: o.log,
     });
-    const feed = new ChangeFeed({ request, onChange: () => notifier.check(), log: o.log, ...o.feed });
+    const feed = new ChangeFeed({ request, socket: () => client.eventsSocket(), onChange: () => notifier.check(), log: o.log, ...o.feed });
     const done = feed.run();
     return {
         notifier,

package/dist/src/onboard.d.ts

@@ -5,8 +5,9 @@ import type { ExecLike } from './doctor.js';
  *   1. connect: add the `ach` MCP server to the agent's own tool (Claude Code
  *      for a claude agent, Codex for a codex one; both found ones for "other")
  *   2. background helper, only with --service: `ach run --install-service`
- *      (+ --notify on a machine with a desktop). Run through npx, `ach` is
- *      installed first, so the helper never runs from the npx cache.
+ *      (+ --notify on a machine with a desktop), which installs and starts it.
+ *      Run through npx, the helper runs the same pinned npx spec as the MCP
+ *      entry, never a path in the npx cache.
  *
  * Pasting the line is the consent: with no terminal (an agent ran it) the steps
  * run and say what they ran. In a terminal each step lists its commands and
@@ -67,7 +68,6 @@ export interface Detected {
     /** User-installed claude / codex (never the bins npx puts on PATH). */
     claude?: string;
     codex?: string;
-    npm?: string;
     npx: boolean;
     /** An `ach` entry already registered (it is replaced). */
     claudeHasAch: boolean;
@@ -86,7 +86,6 @@ export declare function detect(env: NodeJS.ProcessEnv, exec: ExecLike, self: str
 export declare function planSteps(d: Detected, o: {
     home?: string;
     achCmd: Argv;
-    installSpec: string;
     cwd: string;
     zh?: boolean;
     env?: NodeJS.ProcessEnv;

package/dist/src/onboard.js

@@ -1,8 +1,6 @@
-import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { identifyAch, isOurs, MCP_SERVER_NAME, npmSpec, npxAch, thisCliPath, userBin, whichAll } from './invite.js';
-import { VERSION } from './version.js';
+import { identifyAch, isOurs, MCP_SERVER_NAME, npxAch, thisCliPath, userBin, whichAll } from './invite.js';
 /** The closing line: which tool to open and what to say to it. */
 export function doneLine(tools, zh) {
     const names = [...new Set(tools)].map((k) => (k === 'claude' ? 'Claude Code' : 'Codex'));
@@ -65,7 +63,7 @@ export async function detect(env, exec, self, probe) {
     const codex = userBin('codex', env);
     const npx = runFromNpx(self);
     const d = {
-        claude, codex, npm: whichAll('npm', env)[0], npx,
+        claude, codex, npx,
         claudeHasAch: false, codexHasAch: false,
         // run through npx: the MCP entry uses the same pinned spec as the join line
         achCmd: npx ? npxAch() : absoluteAch(env, self),
@@ -111,17 +109,15 @@ export function planSteps(d, o) {
     if (o.service) {
         const notify = o.desktop !== false;
         const helper = ['run', '--install-service', ...(notify ? ['--notify'] : []), '--interactive-first', '--dir', o.cwd];
-        const install = d.npx && d.npm ? [[d.npm, 'install', '-g', o.installSpec]] : [];
         steps.push({
             id: 'service',
             question: [
                 zh
                     ? `安装后台小助手（在 ${o.cwd} 里自动领取任务${notify ? '，并弹出系统通知' : ''}）？会运行：`
                     : `Install the background helper (picks up tasks in ${o.cwd}${notify ? ' and shows desktop notifications' : ''})? This runs:`,
-                ...install.map(() => `  npm install -g ${o.installSpec}    # ${zh ? '`ach` 命令（后台小助手不能从 npx 缓存运行）' : 'the `ach` command (the helper cannot run from the npx cache)'}`),
-                `  ${shellLine(['ach', ...helper])}`,
+                `  ${shellLine([...o.achCmd, ...helper])}`,
             ].join('\n') + '\n',
-            commands: [...install, [...o.achCmd, ...helper]],
+            commands: [[...o.achCmd, ...helper]],
         });
     }
     return steps;
@@ -130,26 +126,16 @@ function yesNo(answer) {
     const a = answer.trim().toLowerCase();
     return !a || /^(y|yes|是|好|ok)$/.test(a);
 }
-/** The global `ach` after `npm install -g` (npm prefix -g)/bin/ach. */
-async function globalAch(npm, exec, env) {
-    const r = await exec(npm, ['prefix', '-g'], env);
-    const prefix = r.stdout.trim().split('\n').pop()?.trim();
-    if (r.code !== 0 || !prefix)
-        return undefined;
-    const f = process.platform === 'win32' ? join(prefix, 'ach.cmd') : join(prefix, 'bin', 'ach');
-    return existsSync(f) ? f : undefined;
-}
 /** Run (or, with --dry-run, only print) the setup after `ach join`. */
 export async function runSetup(io, o) {
     const env = io.env;
     const self = o.self ?? thisCliPath();
     const d = await detect(env, io.exec, self, !o.dryRun);
-    const installSpec = npmSpec(VERSION);
     const home = env.AGENTCHANNEL_HOME || undefined;
     const result = { ran: [], skipped: [], failed: [], tools: [] };
     const zh = !!o.zh;
     const desktop = hasDesktop(env);
-    const plan = planSteps(d, { home, achCmd: d.achCmd, installSpec, cwd: io.cwd, zh, env, runtime: o.runtime, service: o.service, desktop });
+    const plan = planSteps(d, { home, achCmd: d.achCmd, cwd: io.cwd, zh, env, runtime: o.runtime, service: o.service, desktop });
     if (o.dryRun) {
         printOnly(io, d, plan, { zh, join: o.join });
         return result;
@@ -192,18 +178,7 @@ export async function runSetup(io, o) {
             continue;
         }
         if (s.id === 'service') {
-            // run through npx: install `ach` first; the helper then runs the installed one, never the npx cache
-            let helper = s.commands.at(-1);
-            if (s.commands.length > 1) {
-                if (!(await runCmds(s.commands.slice(0, -1)))) {
-                    result.failed.push('service');
-                    continue;
-                }
-                const g = await globalAch(d.npm, io.exec, env);
-                if (g)
-                    helper = [g, ...helper.slice(d.achCmd.length)];
-            }
-            const ok = await installAndStartService(io, helper);
+            const ok = await installService(io, s.commands[0]);
             (ok ? result.ran : result.failed).push('service');
             continue;
         }
@@ -223,36 +198,22 @@ export async function runSetup(io, o) {
     }
     return result;
 }
-/** `ach run --install-service --json`, then start the unit (unless ACH_SERVICE_DIR points elsewhere: tests). */
-async function installAndStartService(io, argv) {
-    const env = io.env;
-    const r = await io.exec(argv[0], [...argv.slice(1), '--json'], env);
-    if (r.code !== 0) {
-        io.err(`  failed (exit ${r.code}): ${shellLine(argv)}${r.stderr.trim() ? `\n  ${r.stderr.trim().split('\n')[0]}` : ''}`);
-        return false;
-    }
-    let f;
+/** `ach run --install-service --json`: it writes the unit and starts it (not under ACH_SERVICE_DIR: tests). */
+async function installService(io, argv) {
+    const r = await io.exec(argv[0], [...argv.slice(1), '--json'], io.env);
+    let f = {};
     try {
         f = JSON.parse(r.stdout);
     }
     catch {
-        io.err('  could not read the service file location');
-        return false;
-    }
-    io.out(`  wrote ${f.path}`);
-    const starts = f.start.map((x) => x.replace(/\s+#.*$/, '')).filter((x) => !/loginctl/.test(x));
-    if (env.ACH_SERVICE_DIR) {
-        io.out(`  start it with: ${starts.join(' && ')}`);
-        return true;
+        /* reported below */
     }
-    for (const c of starts) {
-        const s = await io.exec('/bin/sh', ['-c', c], env);
-        if (s.code !== 0) {
-            io.err(`  failed (exit ${s.code}): ${c}`);
-            return false;
-        }
+    if (r.code !== 0 || !f.path) {
+        const why = f.error || r.stderr.trim().split('\n')[0];
+        io.err(`  failed (exit ${r.code}): ${shellLine(argv)}${why ? `\n  ${why}` : ''}`);
+        return false;
     }
-    io.out('  started');
+    io.out(f.started ? `  installed and started ${f.path}` : `  wrote ${f.path}; start it with: ${(f.start ?? []).join(' && ')}`);
     return true;
 }
 /** --dry-run: print what would be run (nothing is run, not even read-only probes). */

package/dist/src/service.d.ts

@@ -1,14 +1,13 @@
 /**
  * P4: `ach run --install-service` writes a macOS launchd agent or a Linux
- * systemd user unit that starts this runner at login and restarts it. It only
- * writes the file and prints how to start it; it never loads the unit.
+ * systemd user unit that starts this runner at login and restarts it, then
+ * loads it (startService).
  */
 export interface ServiceSpec {
     platform: 'darwin' | 'linux';
     agentName: string;
-    /** node binary and cli.js of this install. */
-    node: string;
-    cli: string;
+    /** What starts the CLI: node + cli.js of an install, or `npx -y <spec>` when it runs from the npx cache. */
+    command: string[];
     /** `run` arguments, without --install-service. */
     args: string[];
     env: Record<string, string>;
@@ -25,5 +24,5 @@ export declare function serviceLabel(agentName: string): string;
 export declare function launchdPlist(s: ServiceSpec): string;
 export declare function systemdUnit(s: ServiceSpec): string;
 export declare function serviceFile(s: ServiceSpec, dir?: string): ServiceFile;
-/** Write the unit file (mode 0644; it holds no secrets). Never loads it. */
+/** Write the unit file (mode 0644; it holds no secrets). */
 export declare function writeServiceFile(f: ServiceFile): void;

package/dist/src/service.js

@@ -14,7 +14,7 @@ export function serviceLabel(agentName) {
     return `io.agentchannel.runner.${agentName.replace(/[^A-Za-z0-9-]/g, '-')}`;
 }
 export function launchdPlist(s) {
-    const progArgs = [s.node, s.cli, 'run', ...s.args].map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    const progArgs = [...s.command, 'run', ...s.args].map((a) => `    <string>${xml(a)}</string>`).join('\n');
     const env = Object.entries(s.env)
         .map(([k, v]) => `    <key>${xml(k)}</key>\n    <string>${xml(v)}</string>`)
         .join('\n');
@@ -50,7 +50,7 @@ ${env}
 `;
 }
 export function systemdUnit(s) {
-    const exec = [s.node, s.cli, 'run', ...s.args].map(sd).join(' ');
+    const exec = [...s.command, 'run', ...s.args].map(sd).join(' ');
     const env = Object.entries(s.env)
         .map(([k, v]) => `Environment=${sd(`${k}=${v}`)}`)
         .join('\n');
@@ -79,7 +79,9 @@ export function serviceFile(s, dir) {
         return {
             path,
             content: launchdPlist(s),
-            start: [`launchctl bootstrap gui/$(id -u) ${path}`],
+            // bootout first: bootstrap refuses a label that is already loaded (a reinstall); bootout returns before the
+            // old job is gone, so a bootstrap right after it can fail once (error 5): try again after a moment
+            start: [`launchctl bootout gui/$(id -u)/${label} 2>/dev/null; launchctl bootstrap gui/$(id -u) ${path} 2>/dev/null || { sleep 2; launchctl bootstrap gui/$(id -u) ${path}; }`],
             stop: [`launchctl bootout gui/$(id -u)/${label}`],
         };
     }
@@ -88,11 +90,12 @@ export function serviceFile(s, dir) {
     return {
         path,
         content: systemdUnit(s),
-        start: ['systemctl --user daemon-reload', `systemctl --user enable --now ${unit}`, `loginctl enable-linger "$USER"   # optional: keep it running while logged out`],
+        // restart, not `enable --now`: a reinstall must pick up the new unit
+        start: ['systemctl --user daemon-reload', `systemctl --user enable ${unit}`, `systemctl --user restart ${unit}`],
         stop: [`systemctl --user disable --now ${unit}`],
     };
 }
-/** Write the unit file (mode 0644; it holds no secrets). Never loads it. */
+/** Write the unit file (mode 0644; it holds no secrets). */
 export function writeServiceFile(f) {
     const dir = join(f.path, '..');
     if (!existsSync(dir))

package/dist/src/version.d.ts

@@ -1,3 +1,3 @@
-export declare const VERSION = "3.2.0";
+export declare const VERSION = "3.4.0";
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export declare const PKG_NAME = "@koalaauto/agentchannel";

package/dist/src/version.js

@@ -1,3 +1,3 @@
-export const VERSION = '3.2.0';
+export const VERSION = '3.4.0';
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export const PKG_NAME = '@koalaauto/agentchannel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalaauto/agentchannel",
-  "version": "3.2.0",
+  "version": "3.4.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",