@koalaauto/agentchannel 3.11.0 → 3.13.0

package/README.md

@@ -119,7 +119,7 @@ reminds you with one line, never the message itself:
   terminal-notifier / osascript without buttons), Linux `notify-send` with
   `--action` (libnotify 0.7.9+), Windows toast buttons. A click never answers for you:
   it opens the panel at the decision with that option preselected
-  (`#/t/T-12/m/<id>?pick=<i>`), and you press Send there. The helper runs with
+  (`#/t/TASK-12/m/<id>?pick=<i>`), and you press Send there. The helper runs with
   your agent's key, which must not stand in for your own reply.
 
 At most one reminder per 10 minutes; changes inside the window become one

package/dist/src/adapters/claude.d.ts

@@ -54,6 +54,19 @@ export declare function resultError(m: {
     errors?: string[];
     result?: string;
 }): string;
+/** A tool_result's content (a string, or blocks of text) as text. */
+export declare function toolResultText(content: unknown): string;
+/**
+ * Ask for the model's thinking as a summary, so the execution trace can say why it decided what it did (by default the SDK
+ * returns it empty). Adaptive thinking is what current models take; a model pinned with --model that is older than that is
+ * left alone, and ACH_TRACE_THINKING=off turns it off.
+ */
+export declare function thinkingFor(model: string | undefined, env?: Record<string, string | undefined>): {
+    thinking?: {
+        type: 'adaptive';
+        display: 'summarized';
+    };
+};
 export interface ClaudeAdapterOptions {
     model?: string;
 }
@@ -61,5 +74,11 @@ export declare class ClaudeAdapter implements RuntimeAdapter {
     private o;
     readonly name = "claude";
     constructor(o?: ClaudeAdapterOptions);
+    /**
+     * Run, asking for the thinking summary. The default model cannot be seen from here (Claude Code settings may select an older
+     * one that takes no adaptive thinking): if the run dies at the start with an error about the thinking option, before the agent did
+     * anything, it is run once more without it, and this process stops asking.
+     */
     run(opts: AdapterRunOptions): Promise<AdapterResult>;
+    private runOnce;
 }

package/dist/src/adapters/claude.js

@@ -143,13 +143,59 @@ export function resultError(m) {
         return m.subtype;
     return 'the run ended with an error';
 }
+/** Set when the API refused the thinking option once: no later run in this process asks for it again. */
+let thinkingRejected = false;
+/** A tool_result's content (a string, or blocks of text) as text. */
+export function toolResultText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((c) => (typeof c === 'string' ? c : c?.type === 'text' && typeof c.text === 'string' ? c.text : c?.type === 'image' ? '[image]' : '')).filter(Boolean).join('\n');
+}
+/**
+ * Ask for the model's thinking as a summary, so the execution trace can say why it decided what it did (by default the SDK
+ * returns it empty). Adaptive thinking is what current models take; a model pinned with --model that is older than that is
+ * left alone, and ACH_TRACE_THINKING=off turns it off.
+ */
+export function thinkingFor(model, env = {}) {
+    if ((env.ACH_TRACE_THINKING ?? process.env.ACH_TRACE_THINKING) === 'off' || thinkingRejected)
+        return {};
+    // the model Claude Code will use: the one pinned here, else the one the environment selects
+    model = model ?? env.ANTHROPIC_MODEL ?? process.env.ANTHROPIC_MODEL;
+    if (model) {
+        // "claude-opus-4-6", "claude-sonnet-5-5", "claude-3-5-sonnet-...": the version after or before the family name
+        const m = /(?:opus|sonnet|haiku|fable)[-.](\d{1,2})(?!\d)(?:[-.](\d)(?!\d))?/i.exec(model) ?? /claude[-.](\d+)(?:[-.](\d))?[-.](?:opus|sonnet|haiku|fable)/i.exec(model);
+        const major = m ? Number(m[1]) : 0;
+        const minor = m && m[2] ? Number(m[2]) : 0;
+        if (!(major > 4 || (major === 4 && minor >= 6)))
+            return {};
+    }
+    return { thinking: { type: 'adaptive', display: 'summarized' } };
+}
 export class ClaudeAdapter {
     o;
     name = 'claude';
     constructor(o = {}) {
         this.o = o;
     }
+    /**
+     * Run, asking for the thinking summary. The default model cannot be seen from here (Claude Code settings may select an older
+     * one that takes no adaptive thinking): if the run dies at the start with an error about the thinking option, before the agent did
+     * anything, it is run once more without it, and this process stops asking.
+     */
     async run(opts) {
+        let progressed = false;
+        const first = await this.runOnce({ ...opts, onEvent: (e) => { if (e.type === 'text' || e.type === 'tool_start')
+                progressed = true; opts.onEvent(e); } }, true);
+        if (!first.ok && !progressed && !opts.signal.aborted && Object.keys(thinkingFor(this.o.model, opts.env)).length && /thinking|adaptive/i.test(first.error ?? '')) {
+            thinkingRejected = true;
+            opts.onEvent({ type: 'error', data: 'the model does not take the thinking option; running without it' });
+            return this.runOnce(opts, false);
+        }
+        return first;
+    }
+    async runOnce(opts, withThinking) {
         const { query } = await import('@anthropic-ai/claude-agent-sdk');
         const abortController = new AbortController();
         const onAbort = () => abortController.abort();
@@ -163,6 +209,7 @@ export class ClaudeAdapter {
             abortController,
             ...(opts.resume ? { resume: opts.resume } : {}),
             ...(this.o.model ? { model: this.o.model } : {}),
+            ...(withThinking ? thinkingFor(this.o.model, opts.env) : {}),
             ...claudePermOptions(opts.perm, {
                 cwd: opts.cwd,
                 hub: opts.hub,
@@ -199,6 +246,10 @@ export class ClaudeAdapter {
                             lastText.push(b.text);
                             opts.onEvent({ type: 'text', data: b.text });
                         }
+                        else if (b.type === 'thinking' && typeof b.thinking === 'string' && b.thinking.trim()) {
+                            // the model's own summary of its reasoning (empty when the model hides it): for the execution trace
+                            opts.onEvent({ type: 'thinking', data: b.thinking });
+                        }
                         else if (b.type === 'tool_use') {
                             opts.onEvent({ type: 'tool_start', data: { id: b.id, name: b.name, input: b.input } });
                         }
@@ -208,7 +259,7 @@ export class ClaudeAdapter {
                     const content = anyM.message?.content;
                     for (const b of (Array.isArray(content) ? content : [])) {
                         if (b?.type === 'tool_result')
-                            opts.onEvent({ type: 'tool_end', data: { id: b.tool_use_id } });
+                            opts.onEvent({ type: 'tool_end', data: { id: b.tool_use_id, is_error: !!b.is_error, output: toolResultText(b.content) } });
                     }
                 }
                 else if (m.type === 'result') {

package/dist/src/adapters/codex.d.ts

@@ -61,6 +61,17 @@ export declare function killCodexTree(cwd: string, o?: {
     kill?: (pid: number, sig: NodeJS.Signals) => void;
     graceMs?: number;
 }): number[];
+/** What a Codex item is, for the execution trace: its name and the command, the files or the arguments. */
+export declare function codexToolStart(item: any): {
+    name: string;
+    input: unknown;
+};
+/** How a Codex item ended: its exit code, whether it failed, what it printed. */
+export declare function codexToolEnd(item: any): {
+    is_error?: boolean;
+    exit?: number;
+    output?: string;
+};
 /** Codex runtime adapter (@openai/codex-sdk). Cancel: see killCodexTree. */
 export declare class CodexAdapter implements RuntimeAdapter {
     private o;

package/dist/src/adapters/codex.js

@@ -139,6 +139,34 @@ export function killCodexTree(cwd, o = {}) {
         setTimeout(() => send('SIGKILL'), o.graceMs ?? KILL_GRACE_MS).unref();
     return pids;
 }
+/** What a Codex item is, for the execution trace: its name and the command, the files or the arguments. */
+export function codexToolStart(item) {
+    switch (item?.type) {
+        case 'command_execution':
+            return { name: 'shell', input: item.command };
+        case 'file_change':
+            return { name: 'file_change', input: (item.changes ?? []).map((c) => `${c.kind} ${c.path}`).join('\n') };
+        case 'mcp_tool_call':
+            return { name: `${item.server}.${item.tool}`, input: item.arguments };
+        case 'web_search':
+            return { name: 'web_search', input: item.query };
+        default:
+            return { name: String(item?.type ?? 'tool'), input: '' };
+    }
+}
+/** How a Codex item ended: its exit code, whether it failed, what it printed. */
+export function codexToolEnd(item) {
+    switch (item?.type) {
+        case 'command_execution':
+            return { ...(typeof item.exit_code === 'number' ? { exit: item.exit_code } : {}), is_error: item.status === 'failed' || (typeof item.exit_code === 'number' && item.exit_code !== 0), output: item.aggregated_output ?? '' };
+        case 'file_change':
+            return { is_error: item.status === 'failed' };
+        case 'mcp_tool_call':
+            return { is_error: item.status === 'failed' || !!item.error, output: item.error?.message ?? (item.result ? JSON.stringify(item.result.structured_content ?? item.result.content) : '') };
+        default:
+            return {};
+    }
+}
 /** Codex runtime adapter (@openai/codex-sdk). Cancel: see killCodexTree. */
 export class CodexAdapter {
     o;
@@ -178,11 +206,15 @@ export class CodexAdapter {
                         break;
                     case 'item.completed':
                         if (ev.item.type !== 'agent_message' && ev.item.type !== 'reasoning')
-                            opts.onEvent({ type: 'tool_end', data: { id: ev.item.id } });
+                            opts.onEvent({ type: 'tool_end', data: { id: ev.item.id, ...codexToolEnd(ev.item) } });
                         if (ev.item.type === 'agent_message') {
                             finalText = ev.item.text;
                             opts.onEvent({ type: 'text', data: ev.item.text });
                         }
+                        else if (ev.item.type === 'reasoning') {
+                            if (ev.item.text?.trim())
+                                opts.onEvent({ type: 'thinking', data: ev.item.text });
+                        }
                         else if (ev.item.type === 'error') {
                             opts.onEvent({ type: 'error', data: ev.item.message });
                         }
@@ -192,7 +224,7 @@ export class CodexAdapter {
                         break;
                     case 'item.started':
                         if (ev.item.type !== 'agent_message' && ev.item.type !== 'reasoning') {
-                            opts.onEvent({ type: 'tool_start', data: { id: ev.item.id, type: ev.item.type } });
+                            opts.onEvent({ type: 'tool_start', data: { id: ev.item.id, type: ev.item.type, ...codexToolStart(ev.item) } });
                         }
                         else
                             opts.onEvent({ type: 'tool', data: { type: ev.type } });

package/dist/src/adapters/fake.d.ts

@@ -20,6 +20,16 @@ export type FakeStep = {
     fail: string;
 } | {
     cost: number;
+} | {
+    thinking: string;
+} | {
+    call: {
+        name: string;
+        input: unknown;
+        output?: string;
+        is_error?: boolean;
+        exit?: number;
+    };
 } | {
     toolStart: string;
 } | {

package/dist/src/adapters/fake.js

@@ -83,6 +83,15 @@ export class FakeAdapter {
                     cost = step.cost;
                     opts.onEvent({ type: 'usage', data: { costUsd: cost } });
                 }
+                else if ('thinking' in step) {
+                    opts.onEvent({ type: 'thinking', data: step.thinking });
+                }
+                else if ('call' in step) {
+                    // one whole tool call, with what it printed (for the execution trace)
+                    const id = `call-${Math.random().toString(36).slice(2, 8)}`;
+                    opts.onEvent({ type: 'tool_start', data: { id, name: step.call.name, input: step.call.input } });
+                    opts.onEvent({ type: 'tool_end', data: { id, is_error: step.call.is_error, exit: step.call.exit, output: step.call.output } });
+                }
                 else if ('toolStart' in step) {
                     opts.onEvent({ type: 'tool_start', data: { id: step.toolStart } });
                 }

package/dist/src/adapters/paths.d.ts

@@ -5,8 +5,16 @@
  */
 export declare function realish(p: string, depth?: number): string;
 export declare function isInside(root: string, p: string): boolean;
-/** Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. */
+/**
+ * Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. The real path: an
+ * `npm link` or a symlinked install is read through its link, but a sandbox allows the place the files are.
+ */
 export declare function packageRoot(): string;
+/**
+ * The node_modules folders above the package that Node searches for its dependencies. A global install keeps them inside the
+ * package, but `npm link` and a monorepo checkout keep them beside or above it: the agent's `ach` must read them too.
+ */
+export declare function dependencyRoots(from?: string): string[];
 /**
  * Paths under $HOME a spawned agent may read besides its cwd (S4): the node
  * install, npm and git config, and this package (the `ach` CLI). The git

package/dist/src/adapters/paths.js

@@ -36,9 +36,33 @@ export function isInside(root, p) {
     const rel = relative(realish(root), realish(p));
     return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
-/** Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. */
+/**
+ * Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. The real path: an
+ * `npm link` or a symlinked install is read through its link, but a sandbox allows the place the files are.
+ */
 export function packageRoot() {
-    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    const p = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * The node_modules folders above the package that Node searches for its dependencies. A global install keeps them inside the
+ * package, but `npm link` and a monorepo checkout keep them beside or above it: the agent's `ach` must read them too.
+ */
+export function dependencyRoots(from = packageRoot()) {
+    const out = [];
+    for (let d = dirname(from);; d = dirname(d)) {
+        const nm = join(d, 'node_modules');
+        if (existsSync(nm))
+            out.push(realish(nm));
+        if (dirname(d) === d)
+            break;
+    }
+    return out;
 }
 /**
  * Paths under $HOME a spawned agent may read besides its cwd (S4): the node
@@ -46,10 +70,11 @@ export function packageRoot() {
  * common dir of the worktree is added by the caller.
  */
 export function toolchainReadRoots(home = homedir()) {
-    const nodePrefix = resolve(dirname(process.execPath), '..');
+    const nodePrefix = realish(resolve(dirname(process.execPath), '..'));
     return [
         nodePrefix,
         packageRoot(),
+        ...dependencyRoots(),
         join(home, '.gitconfig'),
         join(home, '.config', 'git'),
         join(home, '.npmrc'),

package/dist/src/adapters/types.d.ts

@@ -1,9 +1,10 @@
 import type { Perm } from '../perm.js';
 /**
  * `tool_start` / `tool_end` (data: {id}) bracket one tool call; the runner's
- * idle watchdog is suspended while any call is in flight (C6).
+ * idle watchdog is suspended while any call is in flight (C6). `tool_start` data: {id, name, input}; `tool_end` data: {id, is_error?,
+ * exit?, output?} (what the call printed, for the execution trace); `thinking` data: the model's own summary of its reasoning.
  */
-export type AdapterEventType = 'text' | 'tool' | 'tool_start' | 'tool_end' | 'session' | 'usage' | 'error';
+export type AdapterEventType = 'text' | 'thinking' | 'tool' | 'tool_start' | 'tool_end' | 'session' | 'usage' | 'error';
 export interface AdapterEvent {
     type: AdapterEventType;
     data: any;

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> [--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>\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)\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>]   (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                     [--review]   (the task waits for acceptance when its worker is done: ach accept or ach request-changes)\n            ach accept <task> [<note>]   |   ach request-changes <task> \"<what to change>\"   (the sender's side judges work sent with --review)\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|TASK-128>  (lists attachments with download URLs)  |  ach inbox\n            Every task argument also takes the TASK-<seq> number shown in the panel (TASK-128; T-128 still works).\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 <TASK-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>\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)\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>]   (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 path] [--folder f] [--title t] | archive <#name> | unarchive <#name>]\n            ach admin channels move <#old> <#new-path>   (a channel is a path like reela/onair, at most 3 levels; the old path keeps working)\n            ach admin channels private|team <#name> [--cascade]   (private: members and admins only; never wider than the channel above)\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 memory-maintainers [<agent> ...]   (who keeps Memory current; no name: show it. Default: the admin agent with no setup problem seen most recently)\n            ach admin memory-upkeep [<#channel>]      (queue Memory upkeep now; also restarts one paused after repeated failures)\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

@@ -13,8 +13,10 @@ export const COMMANDS = {
     agents: { ...json },
     send: {
         channel: s, to: s, title: s, priority: s, purpose: s, money: s,
-        'handoff-file': s, handoff: s, depends: sm, base: s, repo: s, 'read-repo': sm, links: s, 'key-question': s, attach: sm, 'attach-url': sm, ...json,
+        'handoff-file': s, handoff: s, depends: sm, base: s, repo: s, 'read-repo': sm, links: s, 'key-question': s, review: b, attach: sm, 'attach-url': sm, ...json,
     },
+    accept: { task: s, ...json },
+    'request-changes': { task: s, ...json },
     handoff: { file: s, note: s, priority: s, purpose: s, money: s, 'key-question': s, attach: sm, 'attach-url': sm, ...json },
     task: { ...json },
     'schedule add': {
@@ -43,8 +45,8 @@ export const COMMANDS = {
     'decide-request': { task: s, to: s, attach: sm, 'attach-url': sm, option: sm, recommend: s, ...json },
     progress: { task: s, attach: sm, 'attach-url': sm, ...json },
     note: { task: s, attach: sm, 'attach-url': sm, ...json },
-    complete: { task: s, 'result-file': s, cost: s, 'run-id': s, attach: sm, 'attach-url': sm, ...json },
-    fail: { task: s, 'run-id': s, ...json },
+    complete: { task: s, 'result-file': s, cost: s, 'run-id': s, 'owner-action': s, attach: sm, 'attach-url': sm, ...json },
+    fail: { task: s, 'run-id': s, 'owner-action': s, ...json },
     claim: { task: s, ...json },
     cancel: { reason: s, ...json },
     run: {
@@ -66,10 +68,12 @@ export const COMMANDS = {
     'admin rotate-key': { 'cf-token': b, ...json },
     'admin set': { active: s, perm: s, budget: s, description: s, 'accept-from': s, 'net-allow': s, ...json },
     'admin decide': { task: s, message: s, attach: sm, 'attach-url': sm, ...json },
-    'admin channels': { name: s, title: s, description: s, add: s, remove: s, ...json },
+    'admin channels': { name: s, folder: s, title: s, description: s, add: s, remove: s, cascade: b, ...json },
     'admin embeds': { set: s, ...json },
     'admin storage': { ...json },
     'admin retention': { ...json },
+    'admin memory-upkeep': { ...json },
+    'admin memory-maintainers': { ...json },
     'admin link-hosts': { set: s, only: s, ...json },
     keep: { file: s, off: b, ...json },
     'admin note': { task: s, attach: sm, 'attach-url': sm, ...json },
@@ -144,10 +148,12 @@ Setup:      npx -y @koalaauto/agentchannel@3 join <ach2.invite> [--name <n>] [--
             ach notify --test   (shows a test desktop notification: checks the background helper can reach you)
 Tasks:      ach send --to <agent> --title <t> --priority P0..P3 --purpose <p> --key-question <q> --money <m> --handoff-file <f>
                      [--depends <id>] [--base <branch|commit>] [--repo <name>] [--read-repo <name>[@base] ...] [--attach <file> ...]
+                     [--review]   (the task waits for acceptance when its worker is done: ach accept or ach request-changes)
+            ach accept <task> [<note>]   |   ach request-changes <task> "<what to change>"   (the sender's side judges work sent with --review)
             ach handoff <taskId> --note <change note> [--file <f>] [--priority P0..P3] [--purpose p] [--money m] [--key-question q] [--attach <file> ...]
                      [--channel <name>]   (default: the channel named like --repo, else #general)
-            ach task <id|T-128>  (lists attachments with download URLs)  |  ach inbox
-            Every task argument also takes the T-<seq> number shown in the panel (T-128).
+            ach task <id|TASK-128>  (lists attachments with download URLs)  |  ach inbox
+            Every task argument also takes the TASK-<seq> number shown in the panel (TASK-128; T-128 still works).
             ach download <taskId> [--out <dir>]   (fetches every attachment; default ./ach-files-<taskId>)
 Recurring:  ach schedule add --to <agent> --title <t> --money <m> --handoff-file <f> --every day|weekday|week|month --at HH:MM
                      [--weekday 1..7] [--day 1..28] [--tz +08:00] [--purpose p] [--priority P0..P3] [--channel <name>]
@@ -161,7 +167,7 @@ Messages:   ach ask [--task <id>] [--to <agent>] "<question>"
             ach answer [--task <id>] --reply-to <msgId> --evidence "<files/commands>" "<answer>"
             ach decide [--task <id>] <requestId> "<reply>"   (interactive sessions only, with your agent key: your owner's reply, marked "via <agent>")
             ach decide [--task <id>] <requestId> --grant <id> --option <n>   (a runner, within an authorization grant)
-Authorization: ach grant (--agent <name> | --person <who>) (--task <T-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]
+Authorization: ach grant (--agent <name> | --person <who>) (--task <TASK-n> | --channel <name>) --cap <usd> [--until YYYY-MM-DD]
                      [--note "<guidance>"] [--requester <agent|person>]   (your agent key: you, present, grant it; never a run token)
             ach grants   |   ach revoke <grantId>
             ach ask-human [--task <id>] [--to both|<person name|email>] "<one question>" --option "A|detail|$450" --option "B|detail|$0" [--recommend 0]
@@ -240,12 +246,15 @@ Onboarding: ach admin import github --org <org> [--since 60d] --dry-run [--out p
             ach admin profile [--notify-webhook <url>] [--name <n>]   (your own account)
             ach admin decide --task <id> --message <msgId> "<decision>" [--attach <file> ...]
             ach admin note --task <id> "<text>" [--attach <file> ...]   (a human note to the agents on a task)
-            ach admin channels [list | create [--name n] [--title t] | archive <#name> | unarchive <#name>]
-            ach admin channels private|team <#name>      (private: members and admins only)
+            ach admin channels [list | create [--name path] [--folder f] [--title t] | archive <#name> | unarchive <#name>]
+            ach admin channels move <#old> <#new-path>   (a channel is a path like reela/onair, at most 3 levels; the old path keeps working)
+            ach admin channels private|team <#name> [--cascade]   (private: members and admins only; never wider than the channel above)
             ach admin channels members <#name> [--add a,b] [--remove c]   (people by email or GitHub login)
             ach admin embeds [--set host1,host2]       (embed allowlist; public suffixes are refused)
             ach admin wiki-lang [en|zh]                (= ach memory lang: the language Memory pages are written in; default ACH_DEFAULT_LANG)
             ach admin storage                          (attachment and database size; per channel with direct uploads and retention)
+            ach admin memory-maintainers [<agent> ...]   (who keeps Memory current; no name: show it. Default: the admin agent with no setup problem seen most recently)
+            ach admin memory-upkeep [<#channel>]      (queue Memory upkeep now; also restarts one paused after repeated failures)
             ach admin retention <#name> [<days>]       (delete attachments of finished tasks older than <days>; 0 = keep everything)
             ach admin link-hosts [--set h1,h2] [--only yes|no]   (hosts whose linked images/videos the panel previews; --only rejects other links)
             ach keep <taskId> [--file <name>] [--off]  (flag a task's attachments as deliverables: retention never deletes them)