@sleep2agi/commhub-server 0.9.0-preview.70 → 0.9.0-preview.72

package/src/server.ts

@@ -16,11 +16,11 @@ import { pendingInboxCount } from "./inbox-count.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
-import { canMessageAgent, isAgentRestricted, listAgentGrants, getAgentAccessMode, replaceAgentGrants, restrictedNetworkIds, usernameIsAgentAlias } from "./agent-access.js";
+import { canMessageAgent, isAgentRestricted, listAgentGrants, listGroupGrants, getAgentAccessMode, replaceAgentGrants, restrictedNetworkIds, usernameIsAgentAlias, listAgentGroups, createAgentGroup, updateAgentGroup, replaceAgentGroupMembers, deleteAgentGroup, usersGrantedGroup } from "./agent-access.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { daemonDefaultWorkdirRoot } from "./create-node-validate.js";
-import { register, login, resolveToken, isExpiredSessionToken, sessionIdleDays, listSessions, revokeSession, revokeOtherSessions, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
+import { register, login, resolveToken, isExpiredSessionToken, sessionIdleDays, listSessions, revokeSession, revokeOtherSessions, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, adminDeleteEmptyNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 import { clientRequestIdFromMeta, idempotentTaskId, idempotentTaskMatches, type StoredIdempotentTask } from "./task-idempotency.js";
@@ -42,8 +42,8 @@ import {
   validateAttachments,
   validateIndexEntry,
 } from "./uploads.js";
-import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, unlinkSync, renameSync } from "fs";
-import { dirname as pathDirname } from "path";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, statSync, unlinkSync, renameSync } from "fs";
+import { dirname as pathDirname, join as pathJoin } from "path";
 import { startRetentionSweeper } from "./retention.js";
 import { startStaleSessionSweeper } from "./stale-sweeper.js";
 import {
@@ -274,6 +274,22 @@ function explainExpiredSession(req: Request, res: Response | undefined): Respons
   ));
 }
 
+// 上传文件的归属网络记在磁盘索引 <uploadsRoot>/.index/<file_id>.json 的 network_id 里,不在库里。
+// 管理员删空网络前要数它:目录不存在就是 0;目录读不了就抛(不能把「数不了」当成「没有」)。
+function countNetworkUploads(networkId: string): number {
+  const dir = pathJoin(getUploadsRoot(), ".index");
+  let names: string[];
+  try { names = readdirSync(dir); } catch (e: any) { if (e?.code === "ENOENT") return 0; throw e; }
+  let count = 0;
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      if (JSON.parse(readFileSync(pathJoin(dir, name), "utf8"))?.network_id === networkId) count++;
+    } catch {}
+  }
+  return count;
+}
+
 function userTokenRequired(req: Request): Response {
   return withCors(req, Response.json({ ok: false, error: "user_token_required", message: "this endpoint acts on a user account; node tokens cannot use it" }, { status: 403 }));
 }
@@ -1454,6 +1470,71 @@ return Bun.serve({
       }
     }
 
+    // ── Agent 分组(RFC-038 §8):owner/admin/Hub 管理员管理;组授权动态生效 ──
+    // GET/POST /api/networks/:id/agent-groups · PATCH/DELETE …/:gid · PUT …/:gid/members {node_ids}
+    const groupsMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/agent-groups(?:\/([^/]+)(\/members)?)?$/);
+    if (groupsMatch) {
+      const token = requestToken(req, { allowQueryToken: false });
+      const resolved = token ? resolveToken(token) : null;
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      // 组是人的管理对象,节点令牌不能碰。
+      if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
+      const netId = decodeURIComponent(groupsMatch[1]);
+      const groupId = groupsMatch[2] ? decodeURIComponent(groupsMatch[2]) : null;
+      const membersPath = !!groupsMatch[3];
+      const hubAdmin = resolved.user.role === "admin";
+      const callerRole = getUserNetworkRole(resolved.user.user_id, netId);
+      // 受限成员(以及普通成员)看不到组列表:他们只需要看到最终能访问的 Agent。
+      if (!hubAdmin && callerRole !== "owner" && callerRole !== "admin") {
+        return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+      }
+      const actor = resolved.user;
+      const readBody = async (): Promise<any | null> => {
+        try { const b = await req.json(); return b && typeof b === "object" && !Array.isArray(b) ? b : null; } catch { return null; }
+      };
+      const kick = (userIds: string[]) => { for (const uid of userIds) closeUserStreamsInNetwork(netId, uid); };
+      if (!groupId && req.method === "GET") {
+        return withCors(req, Response.json({ ok: true, network_id: netId, groups: listAgentGroups(netId) }));
+      }
+      if (!groupId && req.method === "POST") {
+        const body = await readBody();
+        if (!body) return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
+        const r = createAgentGroup({ networkId: netId, name: body.name, description: body.description, nodeIds: body.node_ids, actorUserId: actor.user_id });
+        if (!r.ok) return withCors(req, Response.json({ ok: false, error: r.error, ...(r.detail ? { detail: r.detail } : {}) }, { status: r.status }));
+        logAudit(actor.user_id, actor.username, "agent_group_created", "agent_group", r.group.group_id,
+          JSON.stringify({ name: r.group.name, node_ids: r.group.node_ids }).slice(0, 4000), undefined, netId);
+        return withCors(req, Response.json({ ok: true, group: r.group }));
+      }
+      if (groupId && !membersPath && req.method === "PATCH") {
+        const body = await readBody();
+        if (!body) return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
+        const r = updateAgentGroup({ networkId: netId, groupId, name: body.name, description: body.description });
+        if (!r.ok) return withCors(req, Response.json({ ok: false, error: r.error, ...(r.detail ? { detail: r.detail } : {}) }, { status: r.status }));
+        logAudit(actor.user_id, actor.username, "agent_group_renamed", "agent_group", groupId, JSON.stringify({ name: r.group.name }), undefined, netId);
+        return withCors(req, Response.json({ ok: true, group: r.group }));
+      }
+      if (groupId && membersPath && req.method === "PUT") {
+        const body = await readBody();
+        if (!body) return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
+        const r = replaceAgentGroupMembers({ networkId: netId, groupId, nodeIds: body.node_ids, actorUserId: actor.user_id });
+        if (!r.ok) return withCors(req, Response.json({ ok: false, error: r.error, ...(r.detail ? { detail: r.detail } : {}) }, { status: r.status }));
+        logAudit(actor.user_id, actor.username, "agent_group_members_changed", "agent_group", groupId,
+          JSON.stringify({ added: r.added, removed: r.removed }).slice(0, 4000), undefined, netId);
+        // 组成员变了:这个组上有授权的成员按新权限重连(观察流按连接时的权限过滤)。
+        if (r.added.length || r.removed.length) kick(usersGrantedGroup(groupId));
+        return withCors(req, Response.json({ ok: true, group: r.group, added: r.added, removed: r.removed }));
+      }
+      if (groupId && !membersPath && req.method === "DELETE") {
+        const r = deleteAgentGroup(netId, groupId);
+        if (!r.ok) return withCors(req, Response.json({ ok: false, error: r.error }, { status: r.status }));
+        logAudit(actor.user_id, actor.username, "agent_group_deleted", "agent_group", groupId,
+          JSON.stringify({ affected_user_count: r.affected_user_ids.length }), undefined, netId);
+        kick(r.affected_user_ids);
+        return withCors(req, Response.json({ ok: true, affected_user_ids: r.affected_user_ids }));
+      }
+      return withCors(req, Response.json({ ok: false, error: "method not allowed" }, { status: 405 }));
+    }
+
     // ── 多用户 Agent 权限:成员可访问的 Agent(owner/admin 管理) ──
     // GET  → { agent_access: 'all'|'granted', grants: [{node_id, alias, can_message}] }
     // PUT  { grants?: [{node_id | alias, can_message?}] | string[], agent_access?: 'all'|'granted' } → 整体替换
@@ -1482,6 +1563,7 @@ return Bun.serve({
           agent_access: getAgentAccessMode(netId, targetUid),
           restricted: isAgentRestricted(targetUid, netId),
           grants: listAgentGrants(netId, targetUid),
+          group_grants: listGroupGrants(netId, targetUid),
         }));
       }
       // 网络 admin 不能改 owner / 其他 admin 的授权(对他们本来也不生效,但别让 admin 去碰平级)。
@@ -1491,7 +1573,7 @@ return Bun.serve({
       let body: any;
       try { body = await req.json(); } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
       if (!body || typeof body !== "object" || Array.isArray(body)) return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
-      if (body.grants === undefined && body.node_ids === undefined && body.agent_access === undefined) {
+      if (body.grants === undefined && body.node_ids === undefined && body.agent_access === undefined && body.group_grants === undefined) {
         return withCors(req, Response.json({ ok: false, error: "grants or agent_access required" }, { status: 400 }));
       }
       const result = replaceAgentGrants({
@@ -1499,17 +1581,18 @@ return Bun.serve({
         userId: targetUid,
         grants: body.grants ?? body.node_ids,
         agentAccess: body.agent_access,
+        groupGrants: body.group_grants,
         actorUserId: resolved.user.user_id,
       });
       if (!result.ok) {
         return withCors(req, Response.json({ ok: false, error: result.error, ...(result.detail ? { detail: result.detail } : {}) }, { status: result.status }));
       }
       logAudit(resolved.user.user_id, resolved.user.username, "member_agent_grants_changed", "network", netId,
-        JSON.stringify({ user_id: targetUid, agent_access: result.agent_access, grants: result.grants.map((g) => ({ node_id: g.node_id, alias: g.alias, can_message: g.can_message })) }).slice(0, 4000),
+        JSON.stringify({ user_id: targetUid, agent_access: result.agent_access, grants: result.grants.map((g) => ({ node_id: g.node_id, alias: g.alias, can_message: g.can_message })), group_grants: result.group_grants.map((g) => ({ group_id: g.group_id, can_message: g.can_message })) }).slice(0, 4000),
         undefined, netId);
       // 已连着的观察流 / 用户流按旧权限鉴权过,断开让它按新权限重连。
       closeUserStreamsInNetwork(netId, targetUid);
-      return withCors(req, Response.json({ ok: true, network_id: netId, user_id: targetUid, agent_access: result.agent_access, restricted: isAgentRestricted(targetUid, netId), grants: result.grants }));
+      return withCors(req, Response.json({ ok: true, network_id: netId, user_id: targetUid, agent_access: result.agent_access, restricted: isAgentRestricted(targetUid, netId), grants: result.grants, group_grants: result.group_grants }));
     }
 
     // ── 多用户:网络里的人类成员通讯录 —— 任何成员(含受限成员)都能看,只有身份字段 ──
@@ -1689,6 +1772,19 @@ return Bun.serve({
       const resolved = resolveToken(token);
       if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
+      // Hub 管理员删别人的网络:同一个资源、同一个动词,只是换一条判据 —— 只允许空网络
+      // (计数见 auth.ts adminDeleteEmptyNetwork)。owner 自己删仍走下面原来的路径,行为不变。
+      const owner = db.get<{ owner_id: string }>("SELECT owner_id FROM networks WHERE network_id = ?1", netDetailMatch[1]);
+      if (owner && owner.owner_id !== resolved.user.user_id && isHubAdminCredential(resolved)) {
+        const adminResult = adminDeleteEmptyNetwork(netDetailMatch[1], { files: countNetworkUploads(netDetailMatch[1]) });
+        if (!adminResult.ok) {
+          return withCors(req, Response.json({ ok: false, error: adminResult.error, counts: adminResult.counts }, { status: adminResult.status }));
+        }
+        logAudit(resolved.user.user_id, resolved.user.username, "network_deleted", "network", netDetailMatch[1],
+          JSON.stringify({ admin_override: true, owner_id: adminResult.owner_id, network_name: adminResult.network_name, cleaned: adminResult.cleaned }),
+          getClientIP(req, server), netDetailMatch[1]);
+        return withCors(req, Response.json({ ok: true, admin_override: true, cleaned: adminResult.cleaned }));
+      }
       const result = deleteNetwork(resolved.user.user_id, netDetailMatch[1]);
       if (result.ok) logAudit(resolved.user.user_id, resolved.user.username, "network_deleted", "network", netDetailMatch[1]);
       return withCors(req, Response.json(result, { status: result.ok ? 200 : 400 }));
@@ -1999,6 +2095,16 @@ return Bun.serve({
         ? "SELECT alias, status, agent, task, server, updated_at, network_id FROM sessions WHERE 1=1"
         : `SELECT ${SESSION_REST_SELECT} FROM sessions WHERE 1=1`;
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });
+      // `?alias=<name>` narrows to that one agent's rows (same projection, same scope). The app's
+      // chat info / node detail read the full projection for ONE agent; unfiltered that is every
+      // session in the network (533 KB, 94 KB gzip on the production network) per open and per
+      // 10 s poll. Older hubs ignore the parameter and return every row — the app still picks its
+      // row by alias, so old app × new hub and new app × old hub both keep working.
+      const aliasFilter = url.searchParams.get("alias")?.trim();
+      if (aliasFilter) {
+        params.push(aliasFilter);
+        sql += ` AND alias = ?${params.length}`;
+      }
       sql += " ORDER BY updated_at DESC";
       // `model` comes straight from the explicit sessions projection; `runtime` is
       // derived from the raw `agent` field. Both default to null for old nodes
@@ -3353,7 +3459,7 @@ return Bun.serve({
         db.run("DELETE FROM nodes WHERE node_id = ?1", [node.node_id]);
         if (node.alias) {
           db.run(
-            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (?2 IS NULL AND network_id IS NULL))",
+            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (CAST(?2 AS TEXT) IS NULL AND network_id IS NULL))",
             [node.alias, node.network_id ?? null]
           );
         }
@@ -4170,10 +4276,10 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
       `For an additional throwaway instance use bootServer({ port: 0 }).`
     );
   }
-  // The current PostgreSQL adapter opens a fresh process/connection for each
-  // statement, so its transaction() cannot provide the occurrence claim +
-  // task creation atomicity this scheduler requires. Refuse before opening a
-  // listening socket instead of silently running an unsafe scheduler.
+  // The scheduler needs the occurrence claim + task creation to be one
+  // transaction. On an adapter whose transaction() is not atomic, refuse
+  // before opening a listening socket instead of running an unsafe
+  // scheduler.
   assertScheduledTaskBackendSupported();
   const server = bootServer(opts);
 

package/src/side-thread-command-transport.test.ts

@@ -1,12 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import { Database } from "bun:sqlite";
-import { SQLiteAdapter } from "./db-adapter";
+import { PgAdapter, SQLiteAdapter, resolveDatabaseTarget, type DbAdapter } from "./db-adapter";
 import { DurableSideThreadCommandPort, SideThreadCommandStore, handleSideThreadCommandRequest } from "./side-thread-command-transport";
 import { SideThreadCoordinator, SideThreadStore } from "./side-thread";
 
 function actor(tokenId = "tok-node") { return { tokenId, networkId: "net-1", nodeId: "node-1" }; }
+// RFC-039 S4: with COMMHUB_TEST_PG_URL (validated by the adapter guard) the
+// same tests run on PostgreSQL, each fixture on an emptied schema.
+function freshDb(): DbAdapter {
+  if (!process.env.COMMHUB_TEST_PG_URL) return new SQLiteAdapter(new Database(":memory:"));
+  const target = resolveDatabaseTarget();
+  if (target.kind !== "postgres") throw new Error("COMMHUB_TEST_PG_URL did not select PostgreSQL");
+  const pg = new PgAdapter(target.url);
+  pg.exec("DROP SCHEMA public CASCADE; CREATE SCHEMA public");
+  return pg;
+}
 function fixture() {
-  const db = new SQLiteAdapter(new Database(":memory:"));
+  const db = freshDb();
   db.exec("CREATE TABLE inbox(id TEXT PRIMARY KEY, content TEXT)");
   const store = new SideThreadCommandStore(db, () => 123);
   const port = new DurableSideThreadCommandPort({ store, networkForNode: (id) => id === "node-1" ? "net-1" : null,
@@ -178,8 +188,8 @@ describe("Hub durable SideThread command outbox", () => {
     a.close(); b.close();
   });
 
-  test("fails closed on the currently non-atomic PostgreSQL adapter", () => {
-    expect(() => new SideThreadCommandStore({ dialect: "postgres" } as any)).toThrow(/atomic SQLite/);
+  test("fails closed on an adapter without atomic transactions", () => {
+    expect(() => new SideThreadCommandStore({ dialect: "postgres", atomicTransactions: false } as any)).toThrow(/atomic SQLite/);
   });
   test("allows exactly one durable terminal applier", () => {
     const f = fixture(); const close = f.port.subscribe(async () => {});

package/src/side-thread-command-transport.ts

@@ -47,10 +47,10 @@ export function installSideThreadCommandSchema(db: DbAdapter): void {
 
 export class SideThreadCommandStore {
   constructor(readonly db: DbAdapter, private readonly now = Date.now) {
-    // PgAdapter transactions are currently documented non-atomic. Advertising
-    // a durable command outbox on it would be false, so fail closed until a
-    // real PostgreSQL race gate and single-connection transaction land.
-    if (db.dialect !== "sqlite") throw new Error("SideThread command transport requires atomic SQLite transactions");
+    // A durable command outbox needs atomic transactions. Advertising one on
+    // an adapter without them would be false, so fail closed there
+    // (dialect alone does not decide it; see DbAdapter.transactionalFeaturesRefusal).
+    if (db.transactionalFeaturesRefusal !== null) throw new Error(`SideThread command transport requires atomic SQLite transactions${db.transactionalFeaturesRefusal ? `: ${db.transactionalFeaturesRefusal}` : ""}`);
     installSideThreadCommandSchema(db);
   }
 

package/src/side-thread.ts

@@ -450,6 +450,10 @@ export function installSideThreadSchema(database: DbAdapter): void {
     if (!/duplicate column|already exists/i.test(error?.message ?? ""))
       throw error;
   }
+  // RFC-039 F3: operations are listed in insertion order via SQLite's
+  // implicit rowid; PostgreSQL needs a real column for that.
+  if (database.dialect === "postgres")
+    database.exec("ALTER TABLE side_chat_operations ADD COLUMN IF NOT EXISTS rowid BIGSERIAL");
 }
 
 type SideChatRow = {

package/src/status-alias-filter-http.test.ts

@@ -0,0 +1,106 @@
+// GET /api/status?alias=<name> — one agent's rows instead of the whole network.
+// The app's chat info / node detail read the FULL projection for a single agent; unfiltered that
+// was every session (533 KB raw / 94 KB gzip on the production network) per open and per 10 s poll.
+// Old hubs ignore the parameter, so the app keeps picking its row by alias; this suite pins that
+// the filter narrows, never widens (network scope still applies), and that no/blank alias is the
+// old response.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-alias-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusAliasPassw0rd!";
+let aToken = "", aId = "", NET_A = "";
+let bToken = "", bId = "", NET_B = "";
+
+async function get(token: string, path: string) {
+  const res = await fetch(`${BASE}${path}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+function seed(alias: string, node: string, net: string, owner: string, minutesAgo: number) {
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, net, owner]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, ?5, datetime('now', ?6), datetime('now'))`,
+    [`r_${node}`, alias, node, net, `task of ${alias}`, `-${minutesAgo} minutes`],
+  );
+}
+const aliases = (rows: any[]) => rows.map(r => r.alias);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sa_owner_a_${Date.now()}`, PW);
+  aToken = a.token!; aId = a.user!.user_id; NET_A = a.network_id!;
+  const b = register(`sa_owner_b_${Date.now()}`, PW);
+  bToken = b.token!; bId = b.user!.user_id; NET_B = b.network_id!;
+  seed("sa-one", "node_sa_one", NET_A, aId, 1);
+  seed("sa-two", "node_sa_two", NET_A, aId, 2);
+  seed("sa-three", "node_sa_three", NET_A, aId, 3);
+  // Same alias in someone else's network: the filter must not reach it.
+  seed("sa-two", "node_sa_two_b", NET_B, bId, 0);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("/api/status?alias=", () => {
+  test("no alias: every session in scope, newest first (unchanged)", async () => {
+    const r = await get(aToken, `/api/status?network_id=${NET_A}`);
+    expect(r.status).toBe(200);
+    expect(aliases(r.body.sessions)).toEqual(["sa-one", "sa-two", "sa-three"]);
+    expect(r.body.summary.total).toBe(3);
+  });
+
+  test("alias narrows the full projection to that agent", async () => {
+    const r = await get(aToken, `/api/status?network_id=${NET_A}&alias=sa-two`);
+    expect(r.status).toBe(200);
+    expect(aliases(r.body.sessions)).toEqual(["sa-two"]);
+    expect(r.body.sessions[0].node_id).toBe("node_sa_two");
+    // still the full projection (capability bits / host block), not the light one
+    expect(typeof r.body.sessions[0].rules_file_capable).toBe("boolean");
+    expect(r.body.sessions[0].host).toBeDefined();
+    expect(r.body.summary.total).toBe(1);
+  });
+
+  test("alias narrows the light projection too", async () => {
+    const r = await get(aToken, `/api/status?light=1&network_id=${NET_A}&alias=sa-three`);
+    expect(aliases(r.body.sessions)).toEqual(["sa-three"]);
+    expect(r.body.sessions[0].host).toBeUndefined();
+  });
+
+  test("the filter never widens scope: same alias in another network stays invisible", async () => {
+    const scoped = await get(aToken, `/api/status?network_id=${NET_A}&alias=sa-two`);
+    expect(scoped.body.sessions.map((s: any) => s.node_id)).toEqual(["node_sa_two"]);
+    // Unscoped: whatever the caller's scope already shows (the first registered user is an admin
+    // here, so that is both networks) — the filter only picks rows out of it, never adds any.
+    const all = await get(aToken, `/api/status`);
+    const unscoped = await get(aToken, `/api/status?alias=sa-two`);
+    expect(unscoped.body.sessions.map((s: any) => s.node_id)).toEqual(all.body.sessions.filter((s: any) => s.alias === "sa-two").map((s: any) => s.node_id));
+  });
+
+  test("a non-admin member only ever gets their own network's row for a shared alias", async () => {
+    const r = await get(bToken, `/api/status?alias=sa-two`);
+    expect(r.body.sessions.map((s: any) => s.node_id)).toEqual(["node_sa_two_b"]);
+    const other = await get(bToken, `/api/status?alias=sa-one`);
+    expect(other.body.sessions).toEqual([]);
+  });
+
+  test("blank alias is ignored; unknown alias is an empty list, not an error", async () => {
+    expect(aliases((await get(aToken, `/api/status?network_id=${NET_A}&alias=%20`)).body.sessions)).toEqual(["sa-one", "sa-two", "sa-three"]);
+    const none = await get(aToken, `/api/status?network_id=${NET_A}&alias=nobody`);
+    expect(none.status).toBe(200);
+    expect(none.body.sessions).toEqual([]);
+  });
+});

package/src/tools.ts

@@ -1304,14 +1304,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_token_required" }) }],
       };
     }
-    // PgAdapter.transaction currently opens a fresh subprocess/connection
-    // per statement. The all-or-nothing batch promise cannot be made there;
-    // refuse evidence rather than publish a partially stamped batch.
-    if (db.dialect !== "sqlite") {
+    // The all-or-nothing batch promise needs a transaction() that really is
+    // one transaction; refuse evidence on any adapter that cannot give that
+    // rather than publish a partially stamped batch.
+    if (db.transactionalFeaturesRefusal !== null) {
       return {
         content: [{ type: "text" as const, text: JSON.stringify({
           ok: false,
-          error: "task_runtime_evidence_backend_unsupported",
+          error: "task_runtime_evidence_backend_unsupported", message: db.transactionalFeaturesRefusal || undefined,
         }) }],
       };
     }
@@ -5768,6 +5768,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     priority: z.enum(["high", "normal", "low", "lowest"]).optional().describe("high = P0 最高, normal = P1 普通, low = P2 低, lowest = P3 极低"),
     column: z.enum(["pool", "doing", "done"]).optional(),
     due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (stored as UTC seconds); \"\" clears"),
+    start: z.string().max(40).optional().describe("start date (Gantt): same shapes as due; \"\" clears"),
     description: z.string().max(20_000).optional().describe("markdown"),
     checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
     project_id: z.string().max(200).nullable().optional(),
@@ -5779,12 +5780,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   };
   const pick = (args: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => args[k] !== undefined).map(k => [k, args[k]]));
   const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
+  const REQ_ID_DESC = "requirement id (req_…) or its short number \"#N\" (e.g. \"#42\", per network; a user token that sees several networks must also pass network_id, else 409 ambiguous_seq)";
 
   server.tool(
     "requirements_list",
-    "List requirement tasks in your network. Filters: status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived. Newest first, max 500. Each task carries children {total, done}.",
+    "List requirement tasks in your network. Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). Newest first, 500 per page by default (limit ≤ 1000); has_more + next_cursor → pass cursor for the next page. Each task carries children {total, done}.",
     {
       network_id: z.string().max(200).optional(),
+      seq: z.number().int().positive().optional().describe("short number (#N) of one task in this network"),
       status: z.enum(["pool", "doing", "done"]).optional(),
       project_id: z.string().max(200).optional(),
       owner: z.string().max(210).optional(),
@@ -5793,11 +5796,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       external_ref: z.string().max(200).optional(),
       include_archived: z.boolean().optional(),
       parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
-      top_level: z.boolean().optional(),
+      top_level: z.boolean().optional(), q: z.string().max(200).optional(), limit: z.number().int().min(1).max(1000).optional(), cursor: z.string().max(600).optional(),
     },
     async (args) => {
       const q = new URLSearchParams();
-      for (const k of ["status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
       return requirementsCall("GET", `/api/requirements${q.size ? `?${q}` : ""}`, args.network_id);
@@ -5806,8 +5809,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_get",
-    "Get one requirement task by id (with description, checklist, owners, project, external_ref).",
-    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional() },
+    "Get one requirement task by id or by its short number \"#N\" (with description, checklist, owners, project, external_ref, seq).",
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional() },
     async ({ id, network_id }) => requirementsCall("GET", `/api/requirements/${encodeURIComponent(id)}`, network_id),
   );
 
@@ -5820,15 +5823,15 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_update",
-    "Patch a requirement task; omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
-    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
+    "Patch a requirement task (id or \"#N\"); omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
     async (args) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(args, REQ_WRITE_KEYS)),
   );
 
   server.tool(
     "requirements_checklist_toggle",
     "Set one checklist item done / not done (only that item is written, so concurrent edits of other items are kept).",
-    { id: z.string().min(1).max(200), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
     async ({ id, item_id, done, network_id }) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(id)}/checklist/${encodeURIComponent(item_id)}`, network_id, { done }),
   );