agentus 0.3.8 → 0.4.0

package/README.md

@@ -110,6 +110,7 @@ layer never changes.
 |---|---|---|
 | `AGENTUS_PORT` | `8788` | server port (never reads bare `PORT` — that name is polluted on shared hosts) |
 | `AGENTUS_DATA` | `~/.agentus` | where state lives; see "Where your state lives" for the full order (`<repo>/packages/server/.data` on a checkout that already has one) |
+| `AGENTUS_TITLE` | `Agentus` | this instance's own name: the browser tab title and the PWA/home-screen label. Set it when one person runs several cockpits (`AGENTUS_TITLE="Agentus（pre-betabox）"`) |
 | `AGENTUS_HERMES_CMD` | `hermes` | binary to spawn for the hermes backend |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | ditto for qoder |
 | `AGENTUS_HERMES_HOME` | `~/.hermes` | default `HERMES_HOME` for a row that does not name one (the operator's own home) |
@@ -277,6 +278,40 @@ A row that points at its own home needs no permission — only a name. One trap
 a row points elsewhere: a fresh home whose `hindsight/config.json` keeps the default profile
 name `"hermes"` would attach to your production memory daemon, so the row warns when it would.
 
+## The cockpit CLI (for the agents inside it)
+
+An agent in a slot is blind: the other sessions, what they are doing, and what the operator
+asked them all live in the cockpit, not in the agent's prompt. `agentus cockpit` is the one
+channel that lets an agent read that — and, if you allow it, hand a message to another session:
+
+```bash
+"$AGENTUS_COCKPIT_BIN" capabilities                    # the contract, self-describing (start here)
+"$AGENTUS_COCKPIT_BIN" session list --here             # …narrowed: my workspace, newest activity first
+"$AGENTUS_COCKPIT_BIN" session list --waiting --table  # …the operator's approval queue, as a table
+"$AGENTUS_COCKPIT_BIN" session rename <id> "…name…"    # name a session (the row records who did it)
+"$AGENTUS_COCKPIT_BIN" session show <id>               # one session, + what it is waiting on
+"$AGENTUS_COCKPIT_BIN" session messages <id> --tail 20
+"$AGENTUS_COCKPIT_BIN" session plan <id>
+"$AGENTUS_COCKPIT_BIN" session send <id> "…a message…"  # operator-gated, off by default
+"$AGENTUS_COCKPIT_BIN" skill                           # this CLI's own manual, from the package
+```
+
+The shape is noun-then-verb (`agentus session send <id> …`) because every one of these acts on the
+same object; the session id is a positional argument, options stay options.
+
+The cockpit hands `AGENTUS_COCKPIT_BIN/_ENDPOINT/_TOKEN/_SESSION` to each agent it spawns, so
+the CLI needs no arguments, no port and no config — and the token never appears on a command
+line. `AGENTUS_COCKPIT_BIN` is this same `agentus` launcher, so there is one command with one
+name; `agentus cockpit …` at your own shell is the identical thing. Delivering a message (**设置 → 驾驶舱互发消息**, off by default) means the target agent
+*received* it, never that it read or agreed; a busy target refuses with `target_busy` and saw
+nothing.
+
+The manual is `skills/agentus-cockpit/SKILL.md`, shipped in the package. Backends with a native
+skills directory (Hermes: `$HERMES_HOME/skills`) get it installed at spawn — idempotently, by
+content, so a release that changes it refreshes it and a spawn that would not costs nothing.
+Backends without one (Qoder) get a single line in the plan reminder and can read the same file
+with `agentus cockpit skill`, which is also why the document is never pasted into a prompt.
+
 ## What it does today (M0 → M4)
 
 - multi-session rail, **grouped by working directory** — running sessions and **closed

package/README.zh-CN.md

@@ -240,6 +240,37 @@ Hermes 内置的 SQLite 3.50.4（落在 WAL-reset 区间内）在两个写入者
 `hindsight/config.json` 保持默认 profile 名 `"hermes"` 的话，会接上你的生产记忆守护进程，所以这种
 情况下那一行会给出警告。
 
+## 驾驶舱 CLI（给里面的 agent 用）
+
+槽位里的 agent 是瞎子：别的会话在干什么、你让它改什么，都在驾驶舱里，不在它的 prompt 里。
+`agentus cockpit` 是唯一一条让 agent 读到这些的通道 —— 以及（你允许时）把一句话传给另一个会话：
+
+```bash
+"$AGENTUS_COCKPIT_BIN" capabilities                     # 契约本身，自述（先跑这个）
+"$AGENTUS_COCKPIT_BIN" session list --here              # 收窄：我的工作空间，按活跃时间倒序
+"$AGENTUS_COCKPIT_BIN" session list --waiting --table    # 操作者的待审批队列，打成表
+"$AGENTUS_COCKPIT_BIN" session rename <id> "…名字…"      # 给会话改名（行里会记下是谁改的）
+"$AGENTUS_COCKPIT_BIN" session show <id>                # 单个会话，外加它此刻在等什么
+"$AGENTUS_COCKPIT_BIN" session messages <id> --tail 20
+"$AGENTUS_COCKPIT_BIN" session plan <id>
+"$AGENTUS_COCKPIT_BIN" session send <id> "…一句话…"      # 需要操作者开启，默认关闭
+"$AGENTUS_COCKPIT_BIN" skill                            # 这份 CLI 的说明书，直接从包里取
+```
+
+形状是「名词 + 动词」（`agentus session send <id> …`），因为这些动作都作用在同一个对象上；
+会话 id 是位置参数，选项才用 `--`。
+
+身份由驾驶舱在 spawn 时注入（`AGENTUS_COCKPIT_BIN/_ENDPOINT/_TOKEN/_SESSION`），所以 CLI
+不要参数、不要端口、不要配置，token 也不会出现在命令行上。`AGENTUS_COCKPIT_BIN` 就是同一个
+`agentus` 启动器 —— 命令只有一个、名字也只有一个，你在自己 shell 里敲 `agentus cockpit …` 是同一件事。互发消息（**设置 → 驾驶舱互发消息**，
+默认关闭）里的「已送达」只意味着对方 agent **收到**并开始一轮，绝不等于它读懂了或同意了；
+对方正在跑回合时会拒绝并回 `target_busy`，那条消息哪里都没进。
+
+说明书就是 `skills/agentus-cockpit/SKILL.md`，随包发布。有原生技能目录的后端（Hermes：
+`$HERMES_HOME/skills`）在 spawn 时装进去 —— 按内容幂等，所以新版本会刷新、重复 spawn 不产生写盘；
+没有原生目录的后端（Qoder）只在计划提示里拿一行，需要时用 `agentus cockpit skill` 读同一份文件，
+这也正是它永远不被塞进 prompt 的原因。
+
 ## 目前能做什么（M0 → M4）
 
 - 多会话侧栏，**按工作目录分组** —— 运行中的会话和**已关闭的案例**（进程已退出的 transcript；

package/bin/agentus.mjs

@@ -44,6 +44,18 @@ Options
   -h, --help         this text
   -v, --version      print the version
 
+Commands (client side — they need the identity the cockpit gives an agent it spawns)
+  agentus session list                 who you are + every session in scope
+  agentus session show <id>            one session in detail + any approval it waits on
+  agentus session messages <id> [--tail N]
+  agentus session plan <id>
+  agentus session send <id> <text…>    deliver a message into another session (operator-gated)
+  agentus capabilities                 the CLI's contract, self-describing
+  agentus skill [--path]               the CLI's manual, as shipped in the package
+
+  Inside a session they are called as:  "$AGENTUS_COCKPIT_BIN" session list
+  The cockpit hands that path (this very file) plus endpoint/token/session in the environment.
+
 The server reads more environment variables than these (agent backends, auth,
 speech). They are listed in the README, and the boot log prints the ones in play.
 
@@ -67,6 +79,21 @@ function fail(message) {
   }
 }
 
+// Client subcommands, not flags: hand the rest of the argv to the CLI in its own process, so this file
+// keeps holding no product logic. Top-level await keeps the dispatch from indenting the whole launcher
+// into an `else` block.
+//
+// `session` is the noun the five session-scoped verbs hang off; `capabilities` and `skill` sit at the
+// top level because they describe the CLI itself, not a session.
+const CLIENT_NOUNS = new Set(["session", "capabilities", "skill"]);
+if (CLIENT_NOUNS.has(process.argv[2])) {
+  const child = spawn(process.execPath, [path.join(PKG_ROOT, "bin/cli.mjs"), ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  const code = await new Promise((resolve) => child.on("exit", (c, signal) => resolve(signal ? 130 : c ?? 0)));
+  process.exit(code);
+}
+
 const opts = { port: undefined, data: undefined, open: false, where: false };
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i++) {

package/bin/cli.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * `agentus <command>` — the CLI client: sessions, their transcripts and plans, and the gated
+ * cross-session `send`. Dispatched by `bin/agentus.mjs`, which is also what the cockpit hands agents
+ * as `AGENTUS_COCKPIT_BIN`, so there is exactly one command and one spelling everywhere.
+ *
+ * SHAPE: noun, then verb — `agentus session list|show|messages|plan|send`
+ * The five things an agent needs are all about ONE object (a session), so the noun is not decoration:
+ * it keeps `list` from meaning "list what?" and leaves the top level free for the two commands that
+ * are NOT about a session — `capabilities` (this CLI's contract) and `skill` (its manual). The
+ * session id is a POSITIONAL argument, like `docker logs <id>` / `git show <rev>`: it is the object
+ * the verb acts on, not an option, and `--tail` stays an option exactly because it is a modifier.
+ *
+ * IDENTITY AND SECRETS
+ * The cockpit sets `AGENTUS_COCKPIT_ENDPOINT` / `_TOKEN` / `_SESSION` in the agent's own environment
+ * when it spawns it; this file only reads them. NEVER echo/export/print them: one is your session, the
+ * other is the key to it. Nothing here takes a token on the command line — a command line ends up in
+ * `ps` and in shell history, an environment does not.
+ *
+ * OUTPUT CONTRACT
+ * stdout carries ONE JSON document: `{ success, data, meta }`. Anything a human reads goes to stderr,
+ * so a caller can pipe stdout straight into `jq`. A refusal is `{ success: false, error: { code,
+ * message } }` on stdout plus a non-zero exit; the code is a STABLE string (`target_busy`,
+ * `sends_disabled`, …) that a model can branch on.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+/** This package's root — `bin/` is one level down. Resolved from the FILE, never from cwd: the CLI is
+ *  run from inside an agent's session, whose cwd is the operator's project. */
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const ENDPOINT = (process.env.AGENTUS_COCKPIT_ENDPOINT ?? "").replace(/\/+$/, "");
+const TOKEN = process.env.AGENTUS_COCKPIT_TOKEN ?? "";
+const SELF = process.env.AGENTUS_COCKPIT_SESSION ?? "";
+
+const USAGE = `agentus — read the cockpit from inside a session, and (if the operator allowed it) talk to
+another one
+
+  agentus session list [flags]        who you are + the sessions in scope that match
+        --here            only MY workspace (usually what you want)
+        --workspace <p>   only that workspace            --status running|ready|cold
+        --waiting         only sessions with an approval outstanding (the operator's queue)
+        --since <when>    activity within 30m/2h/1d/2w or 2026-10-17[T14:30]
+        --created-since <when>   same grammar, measured against CREATION
+        --grep <text>     title substring        --sort last|created|name
+        --limit N         default 20, max 200    --all include 已归档   --include-self
+        --by workspace    bucket the page by workspace (groups + sessions)
+        --table           print a HUMAN table instead of JSON (for people, not for pipes)
+  agentus session rename <id> <title…> | --auto    name it (attributed to you)
+  agentus session show <id>           one session in detail, with any approval it is waiting on
+  agentus session messages <id> [--tail N]
+                                      the last N messages, each cut to the documented size
+  agentus session plan <id>           the plan object the operator's card renders
+  agentus session send <id> <text…>   deliver a message into another session (stdin if no text)
+
+  agentus capabilities                the contract: commands, fields, truncation, scope, send state
+  agentus skill [--path]              this CLI's manual, as shipped in the package
+
+Operator mode: run outside a session with AGENTUS_DATA (data dir) and AGENTUS_PORT (or
+AGENTUS_ENDPOINT) pointing at your cockpit — the CLI then authenticates with <data>/auth.token, the
+same credential scripts already use. Inside a session it always prefers the cockpit's own variables.
+
+Read "capabilities" first: it is self-describing, so no doc can drift from the code.
+"send" is OFF unless the operator turned 驾驶舱互发消息 on. A busy target answers target_busy and saw
+NOTHING — never report that as delivered, and never claim another session READ your message.
+`;
+
+function out(doc) {
+  process.stdout.write(`${JSON.stringify(doc)}\n`);
+}
+
+function fail(code, message, extra = {}) {
+  out({ success: false, error: { code, message }, ...extra });
+  process.stderr.write(`error [${code}]: ${message}\n`);
+  process.exit(1);
+}
+
+/** Operator mode — a human at a shell, not an agent inside a session.
+ *
+ *  The cockpit already trusts `<DATA_DIR>/auth.token` as the operator credential (it is what scripts
+ *  and CI use), so the same CLI works from a terminal without inventing a second door. Read from the
+ *  FILE, never from argv: the token identifies the operator. Returns null when this is an agent (its
+ *  own variables win) or when there is nothing to authenticate with. */
+function resolveOperator() {
+  if (ENDPOINT && TOKEN && SELF) return null; // an agent: its identity is the cockpit's to give
+  const dataDir = process.env.AGENTUS_DATA || path.join(process.env.HOME ?? "", ".agentus");
+  const file = path.join(dataDir, "auth.token");
+  if (!existsSync(file)) return null;
+  const port = process.env.AGENTUS_PORT || "8788";
+  const endpoint = (process.env.AGENTUS_ENDPOINT || `http://127.0.0.1:${port}`).replace(/\/+$/, "");
+  const token = readFileSync(file, "utf8").trim();
+  return token ? { endpoint, token } : null;
+}
+
+const OPERATOR = resolveOperator();
+const EP = ENDPOINT || OPERATOR?.endpoint || "";
+
+function headers(json = false) {
+  const h = {};
+  if (json) h["content-type"] = "application/json";
+  if (TOKEN) h["x-agentus-cockpit-token"] = TOKEN;
+  else if (OPERATOR) h.authorization = `Bearer ${OPERATOR.token}`;
+  return h;
+}
+
+function needAuth() {
+  if (!EP || (!TOKEN && !OPERATOR)) {
+    fail(
+      "no_identity",
+      "no cockpit to talk to: either run this inside an Agentus session (the cockpit hands the agent AGENTUS_COCKPIT_ENDPOINT/_TOKEN/_SESSION), or from a shell with AGENTUS_DATA pointing at a cockpit whose auth.token you own. Keep your own notes instead.",
+    );
+  }
+}
+
+async function call(pathname) {
+  let res;
+  try {
+    res = await fetch(`${EP}${pathname}`, { headers: headers() });
+  } catch (e) {
+    fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok) fail(String(body?.error ?? `http_${res.status}`), String(body?.error ?? `the cockpit answered HTTP ${res.status}`));
+  return body;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+/** Age in the smallest unit that still reads: 12s / 7m / 3h / 5d. Stale-but-live is the case this is
+ *  for — a session waiting on an approval shows an old age and that is the signal, not a bug. */
+function age(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.round(s / 60)}m`;
+  if (s < 86400) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+function tableRow(s, now) {
+  const dot = s.cold ? "○" : "●";
+  const flags = [s.permissions ? `⏸${s.permissions}` : "", s.plan ? `▶${s.plan.done ?? ""}` : "", s.self ? "self" : ""]
+    .filter(Boolean)
+    .join(" ");
+  const name = String(s.name ?? "").slice(0, 44);
+  return `${dot} ${age(now - (s.lastAt ?? now)).padStart(4)}  ${flags.padEnd(8)} ${s.id}  ${name}`;
+}
+
+/** Grouped when the answer has groups, flat otherwise — one renderer, so `--table` never disagrees with
+ *  `--by workspace` about what the shape of the answer is. */
+function renderTable(data) {
+  const now = Date.now();
+  const self = data?.self;
+  const head = [
+    self ? `you: ${self.id}  ${self.name ?? ""}` : "you: (operator — no session identity)",
+    `${data?.meta?.returned ?? 0}/${data?.meta?.total ?? 0} session(s)${data?.meta?.capped ? ", capped" : ""}`,
+    data?.meta?.applied ? `filters: ${JSON.stringify(data.meta.applied)}` : "",
+  ].filter(Boolean).join("   ·   ");
+  const lines = [head, ""];
+  const groups = data?.groups;
+  if (groups) {
+    for (const g of groups) {
+      lines.push(`${g.key}   (${g.sessions.length})`);
+      for (const s of g.sessions) lines.push(`  ${tableRow(s, now)}`);
+      lines.push("");
+    }
+  } else {
+    for (const s of data?.sessions ?? []) lines.push(tableRow(s, now));
+    lines.push("");
+  }
+  lines.push("● live  ○ cold  ⏸ waiting on approval  ▶ plan");
+  return `${lines.join("\n")}\n`;
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+  process.stderr.write(USAGE);
+  process.exit(cmd ? 0 : 2);
+}
+
+// `skill` answers from the package, with no cockpit involved: the document ships next to this file
+// (`skills/agentus-cockpit/SKILL.md`), so an agent whose backend has no native skill discovery can still
+// read it on demand instead of having it pasted into every prompt. Keep it OUTSIDE the auth gate —
+// needing a token to learn how to use the token would be a locked door with the key behind it.
+if (cmd === "skill") {
+  const doc = path.join(PKG_ROOT, "skills/agentus-cockpit/SKILL.md");
+  if (rest.includes("--path")) {
+    process.stdout.write(`${doc}\n`);
+    process.exit(0);
+  }
+  if (!existsSync(doc)) fail("no_skill", `the skill document is missing from this install (expected ${doc})`);
+  process.stdout.write(readFileSync(doc, "utf8"));
+  process.exit(0);
+}
+
+needAuth();
+const q = (s) => encodeURIComponent(s);
+const meta = (data) => ({ schema_version: data?.schema_version ?? 1, ...(data?.meta ?? {}) });
+
+if (cmd === "capabilities") {
+  const data = await call("/api/cockpit/capabilities");
+  out({ success: true, data, meta: meta(data) });
+} else if (cmd === "session") {
+  const [verb, ...args] = rest;
+  const id = args[0];
+
+  if (verb === "list") {
+    // Flags only after the verb, and the id-less list is the one command where that is the whole
+    // surface: everything here narrows WHICH sessions answer, nothing changes them.
+    const params = new URLSearchParams();
+    // `by` and `table` are display choices: `by` changes the JSON shape (the server buckets), `table`
+    // only changes what this process prints — it never travels as a query the server could act on.
+    const VALUE_FLAGS = ["workspace", "status", "since", "created-since", "grep", "sort", "limit", "by"];
+    const BOOL_FLAGS = ["here", "waiting", "all", "include-self", "table"];
+    // flags start at 0 here: `session list` takes no positional id (unlike show/messages/plan)
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (!a.startsWith("--")) fail("bad_request", `unexpected argument "${a}" (session list takes flags only)`);
+      const name = a.slice(2);
+      if (BOOL_FLAGS.includes(name)) {
+        params.set(name.replaceAll("-", "_"), "1");
+      } else if (VALUE_FLAGS.includes(name)) {
+        const v = args[++i];
+        if (v === undefined) fail("bad_request", `--${name} needs a value`);
+        if (name === "limit" && !/^\d+$/.test(v)) fail("bad_request", `--limit wants a number, got "${v}"`);
+        if (name === "by" && v !== "workspace") fail("bad_request", `--by wants workspace, got "${v}"`);
+        params.set(name.replaceAll("-", "_"), v);
+      } else {
+        fail("bad_request", `unknown flag --${name} (see agentus capabilities)`);
+      }
+    }
+    const wantTable = params.get("table") === "1";
+    params.delete("table");
+    const qs = params.toString();
+    const data = await call(`/api/cockpit/context${qs ? `?${qs}` : ""}`);
+    if (wantTable) {
+      // Human output REPLACES the JSON document on stdout (documented in `capabilities`). Mixing the
+      // two would break both readers: a pipe wants one JSON document, an eye wants columns.
+      process.stdout.write(renderTable(data));
+    } else {
+      out({ success: true, data, meta: meta(data) });
+    }
+  } else if (verb === "rename") {
+    if (!id) fail("bad_request", "usage: agentus session rename <id> <new title…> | --auto");
+    const auto = args.includes("--auto");
+    const title = args.slice(1).filter((a) => a !== "--auto").join(" ").trim();
+    if (!auto && !title) fail("bad_request", "nothing to name it: pass the title after the id, or --auto to clear it");
+    if (auto && title) fail("bad_request", "--auto clears the name; do not also pass a title");
+    let res;
+    try {
+      res = await fetch(`${EP}/api/cockpit/rename`, {
+        method: "POST",
+        headers: headers(true),
+        body: JSON.stringify(auto ? { id, auto: true } : { id, title }),
+      });
+    } catch (e) {
+      fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
+    }
+    const body = await res.json().catch(() => null);
+    if (!res.ok) fail(String(body?.error ?? `http_${res.status}`), String(body?.error ?? `the cockpit answered HTTP ${res.status}`));
+    out({ success: true, data: body, meta: meta(body) });
+  } else if (verb === "show") {
+    if (!id) fail("bad_request", "usage: agentus session show <id>");
+    // Nothing here ignores a stray argument: `show a b` is a typo, and a CLI that silently drops half
+    // of its input is a CLI whose answers you cannot trust (AionUi's parser skips non-flag tokens;
+    // that is fine for its flag-only surface, wrong for one that takes ids).
+    if (args.length > 1) fail("bad_request", `unexpected argument "${args[1]}" (usage: agentus session show <id>)`);
+    const data = await call(`/api/cockpit/session?id=${q(id)}`);
+    out({ success: true, data, meta: meta(data) });
+  } else if (verb === "messages") {
+    if (!id) fail("bad_request", "usage: agentus session messages <id> [--tail N]");
+    const at = args.indexOf("--tail");
+    const tail = at >= 0 ? args[at + 1] : undefined;
+    if (at >= 0 && tail === undefined) fail("bad_request", "--tail needs a number");
+    const leftovers = args.filter((_, i) => i > 0 && i !== at && i !== at + 1);
+    if (leftovers.length) fail("bad_request", `unexpected argument "${leftovers[0]}" (usage: agentus session messages <id> [--tail N])`);
+    const data = await call(`/api/cockpit/messages?id=${q(id)}${tail ? `&tail=${q(tail)}` : ""}`);
+    out({ success: true, data, meta: meta(data) });
+  } else if (verb === "plan") {
+    if (!id) fail("bad_request", "usage: agentus session plan <id>");
+    if (args.length > 1) fail("bad_request", `unexpected argument "${args[1]}" (usage: agentus session plan <id>)`);
+    const data = await call(`/api/cockpit/plan?id=${q(id)}`);
+    out({ success: true, data, meta: meta(data) });
+  } else if (verb === "send") {
+    if (!id) fail("bad_request", "usage: agentus session send <id> <text…>");
+    // The text is the plain words after the id — an agent writing a sentence should not have to
+    // build JSON to say it. With no words, stdin is accepted: either a JSON `{"message": "…"}` (what
+    // older callers sent) or the raw text.
+    let message = args.slice(1).join(" ").trim();
+    if (!message) {
+      const raw = await readStdin();
+      if (raw) {
+        try {
+          const parsed = JSON.parse(raw);
+          message = String(parsed?.message ?? parsed?.text ?? "").trim();
+        } catch {
+          message = raw.trim();
+        }
+      }
+    }
+    if (!message) fail("bad_request", "nothing to send: pass the text after the id, or pipe it on stdin");
+    let res;
+    try {
+      res = await fetch(`${EP}/api/cockpit/send`, {
+        method: "POST",
+        headers: headers(true),
+        body: JSON.stringify({ to: id, message }),
+      });
+    } catch (e) {
+      fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
+    }
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      // The refusal meanings a model must not blur (see `capabilities.discipline`): none of these is
+      // "delivered", and target_busy specifically means the target saw NOTHING.
+      fail(String(body?.error ?? `http_${res.status}`), String(body?.error ?? `the cockpit answered HTTP ${res.status}`));
+    }
+    out({
+      success: true,
+      data: body,
+      meta: {
+        schema_version: 1,
+        note: "delivered means the target agent received it and started a turn — it does NOT mean it read or agreed. Only the operator sees the reply.",
+      },
+    });
+  } else {
+    process.stderr.write(USAGE);
+    fail("bad_request", `unknown session command: ${verb ?? "(none)"}`);
+  }
+} else {
+  process.stderr.write(USAGE);
+  fail("bad_request", `unknown command: ${cmd}`);
+}

package/docs/installation.md

@@ -193,6 +193,7 @@ unless the backend row names another one — see [HERMES_HOME](#hermes_home).
 |---|---|---|
 | `AGENTUS_PORT` | `8788` | server port (never reads bare `PORT`) |
 | `AGENTUS_DATA` | `~/.agentus` | where state lives; see [Data directory](#data-directory) |
+| `AGENTUS_TITLE` | `Agentus` | this instance's own name — the tab title and the PWA label, so several cockpits on one machine are told apart |
 | `AGENTUS_HERMES_CMD` | `hermes` | binary to spawn for the hermes backend |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | ditto for qoder |
 | `AGENTUS_HERMES_HOME` | `~/.hermes` | default `HERMES_HOME` for a row that does not name one |

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.3.8",
+ "version": "0.4.0",
  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
  "license": "Apache-2.0",
  "repository": {
@@ -15,6 +15,7 @@
   "agentus": "bin/agentus.mjs"
  },
  "files": [
+  "skills/",
   "bin/",
   "packages/server/src/",
   "packages/server/mock/",
@@ -52,6 +53,7 @@
   "workspace-smoke": "node scripts/workspace-smoke.mjs",
   "voice-smoke": "node scripts/voice-smoke.mjs",
   "sentence-units": "tsx scripts/qa/sentence-units.mts",
+  "barge-gate": "tsx scripts/qa/barge-gate.mts",
   "token-format": "tsx scripts/qa/token-format.mts",
   "terminal-palette": "tsx scripts/qa/terminal-palette.mts",
   "android-trust-merge": "node scripts/qa/android-trust-merge.mjs",

package/packages/server/mcp/plan-server.mjs

@@ -43,10 +43,19 @@ const TOOLS = [
       "multi-step task, and again each time a step's status changes — a plan that is not updated is a " +
       "plan that lies. `items` is the WHOLE list as it stands now (a snapshot, not a delta): include " +
       "every step, finished or not, in order. Statuses: pending, in_progress (at most one at a time), " +
-      "completed, cancelled.",
+      "completed, cancelled. Give `title` on your first call for a multi-step task — a short action " +
+      "phrase (max 40 characters) naming the job, because that is the line the operator's completion " +
+      "notification shows on their phone. Without it the notification can only say the session's name.",
     inputSchema: {
       type: "object",
       properties: {
+        title: {
+          type: "string",
+          description:
+            "What this job IS, in one short action phrase (max 40 characters, e.g. 「修复登录超时」). " +
+            "Shown on the completion notification in place of the session name, so make it say the thing " +
+            "the operator would say. Written once; later calls without `title` keep the one stored.",
+        },
         items: {
           type: "array",
           description: "The full plan, in order. Replaces the previous list.",
@@ -104,7 +113,10 @@ function renderPlan(plan) {
   }
   const lines = plan.items.map((i) => `- [${i.status}] ${i.content}`);
   const head = `Plan (revision ${plan.revision ?? 0}${plan.source ? `, source ${plan.source}` : ""}${plan.terminal ? `, ${plan.terminal}` : ""}):`;
-  return [head, ...lines, plan.explanation ? `\nRemark: ${plan.explanation}` : ""].filter(Boolean).join("\n");
+  return [
+    plan.title ? `Title: ${plan.title}` : "",
+    head, ...lines, plan.explanation ? `\nRemark: ${plan.explanation}` : "",
+  ].filter(Boolean).join("\n");
 }
 
 async function callTool(name, args) {
@@ -117,6 +129,9 @@ async function callTool(name, args) {
     if (!items) throw new Error("`items` must be an array of steps");
     const body = await callCockpit("update", {
       items,
+      // Both slots are optional and independent: absent = "keep what is stored", which is what makes a
+      // routine status flip unable to erase the title the completion card reads.
+      ...(args?.title !== undefined ? { title: args.title } : {}),
       ...(args?.explanation !== undefined ? { explanation: args.explanation } : {}),
     });
     const plan = body?.plan;
@@ -128,7 +143,7 @@ async function callTool(name, args) {
     if (body?.accepted === false) {
       return `${body.reason ?? "ignored: this session's plan comes from the agent's own frames"}. The plan on screen is unchanged (${done}/${total} done).`;
     }
-    return `Plan saved (${done}/${total} done${plan?.explanation ? `; remark kept` : ""}). It survives your restarts.`;
+    return `Plan saved (${done}/${total} done${plan?.title ? `; title «${plan.title}»` : ""}${plan?.explanation ? `; remark kept` : ""}). It survives your restarts.`;
   }
   throw new Error(`unknown tool: ${name}`);
 }

package/packages/server/mock/agent.mjs

@@ -179,6 +179,11 @@ const agent = () => ({
         // feature is such a client — it forks the session, asks the fork to summarise, and
         // throws the fork away. Advertising it makes that path testable offline.
         sessionCapabilities: { list: {}, cancel: {}, fork: {} },
+        // Issue #17: ACP lets an agent say which prompt parts it takes, and this one starts out
+        // saying NO to images — the honest default, because a non-vision model is the common case
+        // and a silently dropped image is what the cockpit's gate exists to prevent. `MOCK_IMAGE=1`
+        // flips it, so both sides of the gate are testable without a vision model.
+        promptCapabilities: { image: process.env.MOCK_IMAGE === "1", audio: false, embeddedContext: false },
       },
       authMethods: [{ id: "mock", name: "Mock auth (no-op)" }],
     };
@@ -411,6 +416,20 @@ const agent = () => ({
     // per-turn slow mode: long stream so QA can drop the socket mid-turn (AC6)
     const slow = /\[slow\]/.test(text) ? Math.max(SLOW, 900) : SLOW;
 
+    // `[status]` — the agent-status carrier from issue #18, exactly as hermes' `make_status_cb` sends
+    // it: an EMPTY thought chunk whose `_meta.hermes` holds the sentence. Sent mid-turn on purpose, so a
+    // sweep can prove the line appears while the turn runs and is gone when it ends, and that NOTHING
+    // of it reaches the stored transcript.
+    if (/\[status\]/.test(text)) {
+      setTimeout(() => {
+        void send(agent._conn, sessionId, {
+          sessionUpdate: "agent_thought_chunk",
+          _meta: { hermes: { kind: "status", statusKind: "lifecycle", text: "👁️ Hindsight — recalled 8 memories" } },
+          content: { type: "text", text: "" },
+        }).catch(() => undefined);
+      }, Math.min(slow * 2, 1200));
+    }
+
     // `[table]` — a table fixture for the sorting / full-screen sweep (scripts/qa/table-sweep.mjs).
     // Numeric AND text cells, deliberately NOT in any sorted order, and a local file link plus a
     // relative image, so "clicking a header reorders the rows" and "a relative path resolves" are

package/packages/server/src/acp/backends.ts

@@ -54,6 +54,25 @@ export interface BackendSpec {
   env?: Record<string, string>;
   /** hermes profile, composed into argv by registry.effectiveArgs (`hermes -p <profile> acp`) */
   profile?: string | null;
+  /**
+   * Where this agent looks for skills, if it has such a place. `{home}` is the home we hand the child.
+   *
+   * ACP defines no skill object, so discovery is per-vendor (AionCore keys it off a per-agent
+   * `native_skills_dirs`; see docs/refs/aionui-acp-rules.md). A row that names a dir gets this
+   * package's skills installed there at spawn; a row that does not gets the one-line prompt hint and
+   * can still read the same document on demand (`agentus cockpit skill`). Absent ≠ broken.
+   */
+  skillsDir?: string;
+  /**
+   * The env var this vendor reads as "extra skill roots for THIS process", when it has one.
+   *
+   * This is the first choice and `skillsDir` is the fallback: it scopes our skills to the one agent
+   * process we spawn, so the operator's own `~/.hermes` (shared with Studio, the CLI and every other
+   * Hermes on the box) never learns that Agentus exists. Hermes names it
+   * `HERMES_EXTERNAL_SKILLS_DIRS`, the per-process half of `skills.external_dirs` — see the upstream
+   * PR draft in the workspace (`areas/upstream-prs/`), because stock Hermes has no such variable yet.
+   */
+  skillsEnv?: string;
   /** free-form note shown next to the row in the UI */
   notes?: string;
 }
@@ -78,6 +97,12 @@ export const BACKENDS: Record<string, BackendSpec> = {
       homeVar: "HERMES_HOME",
       homeDefault: defaultHermesHome,
     },
+    // `hermes skill_view` scans <HERMES_HOME>/skills/<name>/SKILL.md at session start — writing there
+    // would land in the operator's REAL home, which Studio and every terminal `hermes` also read. So
+    // we hand the child one more root for its own lifetime instead (no copy, no stale twin, nothing
+    // outside Agentus sees it). `skillsDir` stays as the documented fallback for vendors that only
+    // know how to scan their home.
+    skillsEnv: "HERMES_EXTERNAL_SKILLS_DIRS",
   },
   qoder: {
     label: "Qoder",

package/packages/server/src/acp/registry.ts

@@ -271,6 +271,12 @@ export function rowToSpec(row: BackendRow): BackendSpec {
     needsLoginHint: row.kind === "qoder" ? "qodercli login" : undefined,
     env: { ...(row.env ?? {}) },
     profile: row.profile,
+    // `skillsDir` is a property of the AGENT KIND, not of the operator's row: where a vendor looks
+    // for skills is not something a settings page should have to know. Taken from the builtin of the
+    // same kind, so a stored row inherits it and a new hermes row needs no migration (this is the bug
+    // that made the first install silently skip every real row — stored rows never reach BACKENDS).
+    skillsDir: BACKENDS[row.kind as keyof typeof BACKENDS]?.skillsDir,
+    skillsEnv: BACKENDS[row.kind as keyof typeof BACKENDS]?.skillsEnv,
   };
   if (row.kind === "hermes") {
     spec.isolation = {