@sleep2agi/commhub-server 0.8.3-preview.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.8.3-preview.1",
+  "version": "0.8.3",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/db.ts

@@ -129,6 +129,7 @@ for (const col of [
   { name: "requires_response", def: "TEXT DEFAULT 'reply'" },
   { name: "expires_at", def: "TEXT" },
   { name: "scope", def: "TEXT DEFAULT 'single'" },
+  { name: "meta_json", def: "TEXT" },
 ]) {
   try { db.exec(`ALTER TABLE inbox ADD COLUMN ${col.name} ${col.def}`); } catch {}
 }
@@ -489,6 +490,7 @@ try { db.exec("CREATE INDEX IF NOT EXISTS idx_completions_network ON completions
 // admin to see the answer even if 指挥室's own session has died. The hub forwards
 // the reply up the chain via parent_task_id.
 try { db.exec("ALTER TABLE tasks ADD COLUMN parent_task_id TEXT"); } catch {}
+try { db.exec("ALTER TABLE tasks ADD COLUMN meta_json TEXT"); } catch {}
 try { db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_task_id)"); } catch {}
 
 // Helpers

package/src/index.ts

@@ -5,7 +5,7 @@ import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit } from "./db.js";
 import { createSSEStream, pushEvent, getSSEStats } from "./push.js";
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
-import { prepareRename, commitRename, abortRename } from "./rename.js";
+import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -51,6 +51,11 @@ console.info = (...args: any[]) => { pushLog("info", args); _origConsole.info(..
 console.warn = (...args: any[]) => { pushLog("warn", args); _origConsole.warn(...args); };
 console.error = (...args: any[]) => { pushLog("error", args); _origConsole.error(...args); };
 
+function normalizeMetaJson(meta: unknown): string | null {
+  if (!meta || typeof meta !== "object") return null;
+  try { return JSON.stringify(meta); } catch { return null; }
+}
+
 // ── Rate limiter (in-memory, per IP) ──
 const rateLimits = new Map<string, { count: number; resetAt: number }>();
 function checkRateLimit(ip: string, maxPerMinute = 60): boolean {
@@ -343,6 +348,8 @@ const TaskSchema = z.object({
   from: z.string().max(200).optional(),
   network_id: z.string().max(200).optional(),
   parent_task_id: z.string().max(200).optional(),
+  ttl_seconds: z.number().min(1).max(86400).optional(),
+  meta: z.any().optional(),
 });
 
 const BroadcastSchema = z.object({
@@ -918,6 +925,7 @@ Bun.serve({
       let staleSql = "UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'";
       staleSql = addNetworkScope(staleSql, staleParams, restScope);
       db.run(staleSql, staleParams);
+      cleanupCommittedRenameSessions(restScope.networkId ? [restScope.networkId] : restScope.networkIds ?? null);
       const params: any[] = [];
       let sql = "SELECT * FROM sessions WHERE 1=1";
       sql = addNetworkScope(sql, params, restScope);
@@ -1188,9 +1196,12 @@ Bun.serve({
       if (!canRestWriteNetwork(restAuth, taskNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const canonical = resolveCanonicalAlias(taskNetId, body.alias);
+      const targetAlias = canonical.alias;
       const id = crypto.randomUUID();
       const fromSession = body.from || "api";
       const ttlSeconds = (body as any).ttl_seconds || 3600;
+      const metaJson = normalizeMetaJson((body as any).meta);
       // Mirror send_task MCP: write inbox + tasks rows in a single
       // transaction so the dispatch is visible to dashboard's Tasks page
       // and the parent_task_id lineage chain. Previously this endpoint
@@ -1198,35 +1209,35 @@ Bun.serve({
       // dispatched via REST (anet demo, dashboard Dispatch button, etc.).
       db.transaction(() => {
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, from_session, requires_response, network_id)
-           VALUES (?1, ?2, 'task', ?3, ?4, ?5, 'reply', ?6)`,
-          [id, body.alias, body.priority, body.task, fromSession, taskNetId]
+          `INSERT INTO inbox (id, session_name, type, priority, content, from_session, requires_response, network_id, meta_json)
+           VALUES (?1, ?2, 'task', ?3, ?4, ?5, 'reply', ?6, ?7)`,
+          [id, targetAlias, body.priority, body.task, fromSession, taskNetId, metaJson]
         );
         db.run(
-          `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id)
-           VALUES (?1, ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', ?6), ?7, ?8)`,
-          [id, fromSession, body.alias, body.priority, body.task, `+${ttlSeconds} seconds`, taskNetId, body.parent_task_id ?? null]
+          `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id, meta_json)
+           VALUES (?1, ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', ?6), ?7, ?8, ?9)`,
+          [id, fromSession, targetAlias, body.priority, body.task, `+${ttlSeconds} seconds`, taskNetId, body.parent_task_id ?? null, metaJson]
         );
         // Touch session row so the dashboard reflects "task in flight"
         // immediately, without waiting for the agent's report_status to
         // arrive. Updating both `task` and `updated_at` is enough — we
         // leave `status` to the agent (idle → working → idle).
-        const touchParams: any[] = [body.task.slice(0, 200), body.alias];
+        const touchParams: any[] = [body.task.slice(0, 200), targetAlias];
         let touchSql = "UPDATE sessions SET task = ?1, updated_at = datetime('now') WHERE alias = ?2";
         if (taskNetId) { touchSql += " AND network_id = ?3"; touchParams.push(taskNetId); }
         db.run(touchSql, touchParams);
       });
       // SSE push: 秒达
-      const pendingParams: any[] = [body.alias];
+      const pendingParams: any[] = [targetAlias];
       let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       if (taskNetId) { pendingSql += " AND network_id = ?2"; pendingParams.push(taskNetId); }
       const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
-      const sessionParams: any[] = [body.alias];
+      const sessionParams: any[] = [targetAlias];
       let sessionSql = "SELECT 1 FROM sessions WHERE alias = ?1";
       if (taskNetId) { sessionSql += " AND network_id = ?2"; sessionParams.push(taskNetId); }
       const targetSession = db.get<any>(sessionSql, ...sessionParams);
-      if (targetSession) pushEvent(body.alias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority, from: fromSession }, taskNetId);
-      return withCors(req, Response.json({ ok: true, task_id: id, message_id: id }));
+      if (targetSession) pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority, from: fromSession, ...(canonical.renamed ? { renamed_from: body.alias } : {}) }, taskNetId);
+      return withCors(req, Response.json({ ok: true, task_id: id, message_id: id, ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}) }));
     }
 
     // ── REST: broadcast ──

package/src/rename.ts

@@ -23,11 +23,81 @@ export interface RenameResult {
   error?: string;
 }
 
+export interface CanonicalAlias {
+  alias: string;
+  renamed: boolean;
+  renamed_from?: string;
+  chain: string[];
+}
+
 function hasWriteAccess(userId: string, networkId: string): boolean {
   const role = getUserNetworkRole(userId, networkId);
   return !!role && role !== "viewer";
 }
 
+// Resolve committed alias renames (old -> new), following short chains such
+// as A -> B -> C. This is intentionally server-side canonicalization: stale
+// clients may keep reporting/sending to an old alias after commit, and the hub
+// must not let that recreate orphan session rows (#146/#172).
+export function resolveCanonicalAlias(networkId: string | null | undefined, alias: string): CanonicalAlias {
+  if (!networkId || !alias) return { alias, renamed: false, chain: [alias] };
+
+  const chain = [alias];
+  let current = alias;
+  const seen = new Set([alias]);
+  for (let i = 0; i < 8; i++) {
+    const row = db.get<{ new_alias: string }>(
+      "SELECT new_alias FROM rename_txn WHERE network_id = ?1 AND old_alias = ?2 AND status = 'committed' ORDER BY committed_at DESC LIMIT 1",
+      networkId, current
+    );
+    if (!row?.new_alias || seen.has(row.new_alias)) break;
+    current = row.new_alias;
+    chain.push(current);
+    seen.add(current);
+  }
+
+  return {
+    alias: current,
+    renamed: current !== alias,
+    renamed_from: current !== alias ? alias : undefined,
+    chain,
+  };
+}
+
+export function canonicalAliasExists(networkId: string, alias: string, excludingResumeId?: string | null): boolean {
+  const params: any[] = [networkId, alias];
+  let sql = "SELECT 1 FROM sessions WHERE network_id = ?1 AND alias = ?2";
+  if (excludingResumeId) {
+    sql += " AND resume_id != ?3";
+    params.push(excludingResumeId);
+  }
+  return !!db.get<any>(sql, ...params);
+}
+
+export function cleanupRenamedAliasSession(networkId: string | null | undefined, oldAlias: string, newAlias: string): void {
+  if (!networkId || oldAlias === newAlias) return;
+  const existsNew = db.get<any>(
+    "SELECT 1 FROM sessions WHERE network_id = ?1 AND alias = ?2",
+    networkId, newAlias
+  );
+  if (!existsNew) return;
+  db.run("DELETE FROM sessions WHERE network_id = ?1 AND alias = ?2", [networkId, oldAlias]);
+}
+
+export function cleanupCommittedRenameSessions(networkIds: string[] | null = null): void {
+  const params: any[] = [];
+  let sql = "SELECT network_id, old_alias, new_alias FROM rename_txn WHERE status = 'committed'";
+  if (networkIds) {
+    if (networkIds.length === 0) return;
+    const placeholders = networkIds.map((_, i) => `?${i + 1}`).join(", ");
+    sql += ` AND network_id IN (${placeholders})`;
+    params.push(...networkIds);
+  }
+  for (const row of db.all<{ network_id: string; old_alias: string; new_alias: string }>(sql, ...params)) {
+    cleanupRenamedAliasSession(row.network_id, row.old_alias, row.new_alias);
+  }
+}
+
 // PHASE 1 P3 — create a prepared rename_txn row reserving new_alias.
 // CAS guard (RFC §4 risk #3 TOCTOU): new_alias must be free both in the
 // sessions registry AND among in-flight prepared rename_txn rows.
@@ -80,6 +150,7 @@ export function commitRename(userId: string, txnId: string): RenameResult {
   db.run(
     "UPDATE sessions SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
     [txn.new_alias, txn.network_id, txn.old_alias]);
+  cleanupRenamedAliasSession(txn.network_id, txn.old_alias, txn.new_alias);
   db.run(
     "UPDATE nodes SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
     [txn.new_alias, txn.network_id, txn.old_alias]);

package/src/tools.ts

@@ -3,11 +3,22 @@ import { z } from "zod/v4";
 import { db, uuidv4, logTaskEvent, chainReplyToParent } from "./db.js";
 import { pushEvent } from "./push.js";
 import { getUserNetworkRole } from "./auth.js";
+import { canonicalAliasExists, cleanupRenamedAliasSession, resolveCanonicalAlias } from "./rename.js";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
 }
 
+function parseMetaJson(value: unknown): unknown | null {
+  if (!value || typeof value !== "string") return null;
+  try { return JSON.parse(value); } catch { return null; }
+}
+
+function normalizeMetaJson(meta: unknown): string | null {
+  if (!meta || typeof meta !== "object") return null;
+  try { return JSON.stringify(meta); } catch { return null; }
+}
+
 export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false) {
   // Default from_session for outbound tools — extracted from the calling
   // token's binding (ntok_ → node alias, utok_ → username). Without this,
@@ -149,7 +160,36 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!canWrite(effectiveNetId)) {
         return writeDeniedReply(effectiveNetId);
       }
-      console.log(`[${ts()}] ${alias} (${resume_id.slice(0, 8)}) → report_status: ${status}${task ? " | " + task.slice(0, 60) : ""}${effectiveNetId ? " [net]" : ""}`);
+      const canonical = resolveCanonicalAlias(sessionNetId, alias);
+      let effectiveAlias = canonical.alias;
+      if (canonical.renamed) {
+        // A stale process may keep heartbeating with the old alias after a
+        // committed rename. If the new alias is already active, ignore the
+        // stale report and clean the old row instead of letting it recreate
+        // a red/orphan dashboard node (#146/#172). If not active yet, rewrite
+        // the incoming report to the canonical alias so startup can converge.
+        if (canonicalAliasExists(sessionNetId, effectiveAlias, resume_id)) {
+          cleanupRenamedAliasSession(sessionNetId, alias, effectiveAlias);
+          const pendingParams: any[] = [effectiveAlias];
+          let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
+          pendingSql = addScope(pendingSql, pendingParams, effectiveNetId);
+          const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                ok: true,
+                resume_id,
+                alias: effectiveAlias,
+                renamed_from: alias,
+                ignored_stale_alias: true,
+                inbox_count: pending?.cnt ?? 0,
+              }),
+            }],
+          };
+        }
+      }
+      console.log(`[${ts()}] ${effectiveAlias} (${resume_id.slice(0, 8)}) → report_status: ${status}${task ? " | " + task.slice(0, 60) : ""}${effectiveNetId ? " [net]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const trimmedOutput = output?.slice(0, 4000);
       const hostHostname = host?.hostname || hn || null;
       const hostIp = host?.ip || clientIP || null;
@@ -190,7 +230,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
       db.transaction(() => {
         // Only delete same-alias sessions within the same network
-        db.run("DELETE FROM sessions WHERE alias = ?1 AND resume_id != ?2 AND network_id = ?3", [alias, resume_id, sessionNetId]);
+        db.run("DELETE FROM sessions WHERE alias = ?1 AND resume_id != ?2 AND network_id = ?3", [effectiveAlias, resume_id, sessionNetId]);
         db.run(
           `INSERT INTO sessions (resume_id, alias, tmux_name, server, ip, hostname, agent, project_dir, version, status, task, output, progress, score, node_id, session_id, config_path, channels, network_id, model, cpu_load_1min, cpu_cores, mem_total_gb, mem_used_gb, mem_avail_gb, disk_total_gb, disk_used_gb, disk_avail_gb, process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count, last_seen_at, updated_at)
            VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?21, ?22, ?23, ?24, ?25, ?26, ?27, ?28, ?29, ?30, ?31, ?32, ?33, datetime('now'), datetime('now'))
@@ -219,19 +259,20 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
              process_uptime_seconds = COALESCE(?32, sessions.process_uptime_seconds),
              process_in_flight_count = COALESCE(?33, sessions.process_in_flight_count),
              last_seen_at = datetime('now'), updated_at = datetime('now')`,
-          [resume_id, alias, tmux ?? null, srv ?? null, hostIp, hostHostname, ag ?? null, pd ?? null, ver ?? null, status, task ?? null, trimmedOutput ?? null, progress ?? null, score ?? null, node_id ?? null, session_id ?? null, config_path ?? null, channels ?? null, sessionNetId, mdl ?? null, cpuLoad1m, cpuCores, memTotalGb, memUsedGb, memAvailGb, diskTotalGb, diskUsedGb, diskAvailGb, processRssBytes, processRssMb, processCpuPct, processUptimeSeconds, processInFlightCount]
+          [resume_id, effectiveAlias, tmux ?? null, srv ?? null, hostIp, hostHostname, ag ?? null, pd ?? null, ver ?? null, status, task ?? null, trimmedOutput ?? null, progress ?? null, score ?? null, node_id ?? null, session_id ?? null, config_path ?? null, channels ?? null, sessionNetId, mdl ?? null, cpuLoad1m, cpuCores, memTotalGb, memUsedGb, memAvailGb, diskTotalGb, diskUsedGb, diskAvailGb, processRssBytes, processRssMb, processCpuPct, processUptimeSeconds, processInFlightCount]
         );
         if (host || proc) {
           db.run(
             `INSERT INTO agent_telemetry (id, network_id, resume_id, alias, hostname, ip, cpu_load_1min, cpu_cores, mem_total_gb, mem_used_gb, mem_avail_gb, disk_total_gb, disk_used_gb, disk_avail_gb, process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count, created_at)
              VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, datetime('now'))`,
-            [uuidv4(), sessionNetId, resume_id, alias, hostHostname, hostIp, cpuLoad1m, cpuCores, memTotalGb, memUsedGb, memAvailGb, diskTotalGb, diskUsedGb, diskAvailGb, processRssBytes, processRssMb, processCpuPct, processUptimeSeconds, processInFlightCount]
+            [uuidv4(), sessionNetId, resume_id, effectiveAlias, hostHostname, hostIp, cpuLoad1m, cpuCores, memTotalGb, memUsedGb, memAvailGb, diskTotalGb, diskUsedGb, diskAvailGb, processRssBytes, processRssMb, processCpuPct, processUptimeSeconds, processInFlightCount]
           );
         }
       });
-      pushEvent(alias, {
+      pushEvent(effectiveAlias, {
         type: "status_update",
-        alias,
+        alias: effectiveAlias,
+        ...(canonical.renamed ? { renamed_from: alias } : {}),
         status,
         progress: progress ?? null,
         host: statusHostTelemetry,
@@ -241,19 +282,19 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // V2: sync tasks table — report_status(working) → tasks.running
       if (status === "working" && task) {
         try {
-          const runParams: any[] = [alias, task];
+          const runParams: any[] = [effectiveAlias, task];
           let runSql = `UPDATE tasks SET status = 'running', started_at = datetime('now')
              WHERE to_name = ?1 AND status IN ('delivered', 'acked') AND content = ?2`;
           runSql = addScope(runSql, runParams, effectiveNetId);
           const runResult = db.run(runSql, runParams);
           if (runResult.changes > 0) {
             // Find task_id for logging
-            const findParams: any[] = [alias, task];
+            const findParams: any[] = [effectiveAlias, task];
             let findSql = "SELECT task_id FROM tasks WHERE to_name = ?1 AND content = ?2 AND status = 'running'";
             findSql = addScope(findSql, findParams, effectiveNetId);
             findSql += " ORDER BY started_at DESC LIMIT 1";
             const t = db.get<{ task_id: string }>(findSql, ...findParams);
-            if (t) logTaskEvent(t.task_id, null, "running", alias);
+            if (t) logTaskEvent(t.task_id, null, "running", effectiveAlias);
           }
         } catch {}
       }
@@ -277,13 +318,13 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
                hostname = COALESCE(?9, nodes.hostname),
                network_id = COALESCE(?10, nodes.network_id),
                updated_at = datetime('now')`,
-            [node_id, nn || alias, alias, nodeRuntime, mdl ?? null, config_path ?? null, channels ?? null, srv ?? null, hn ?? null, effectiveNetId ?? null]
+            [node_id, nn || effectiveAlias, effectiveAlias, nodeRuntime, mdl ?? null, config_path ?? null, channels ?? null, srv ?? null, hn ?? null, effectiveNetId ?? null]
           );
         } catch {}
       }
 
       // inbox uses alias for routing
-      const inboxParams: any[] = [alias];
+      const inboxParams: any[] = [effectiveAlias];
       let inboxSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       inboxSql = addScope(inboxSql, inboxParams, effectiveNetId);
       const row = db.get<{ cnt: number }>(inboxSql, ...inboxParams);
@@ -295,7 +336,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             text: JSON.stringify({
               ok: true,
               resume_id,
-              alias,
+              alias: effectiveAlias,
+              ...(canonical.renamed ? { renamed_from: alias } : {}),
               inbox_count: row?.cnt ?? 0,
             }),
           },
@@ -407,13 +449,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const rows0 = db.get<{ cnt: number }>(countSql, ...countParams);
       console.log(`[${ts()}] ${alias} → get_inbox: ${rows0?.cnt ?? 0} pending messages`);
       const rowsParams: any[] = [alias];
-      let rowsSql = `SELECT id, type, priority, content, context, from_session, created_at, network_id
+      let rowsSql = `SELECT id, type, priority, content, context, from_session, created_at, network_id, meta_json
          FROM inbox WHERE session_name = ?1 AND acked = 0`;
       rowsSql = addReadScope(rowsSql, rowsParams, readScope);
       rowsSql += ` ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'normal' THEN 1 ELSE 2 END, created_at
          LIMIT ?${rowsParams.length + 1}`;
       rowsParams.push(limit);
-      const rows = db.all(rowsSql, ...rowsParams);
+      const rows = db.all(rowsSql, ...rowsParams).map((row: any) => ({
+        ...row,
+        meta: parseMetaJson(row.meta_json),
+      }));
 
       return {
         content: [{ type: "text" as const, text: JSON.stringify({ ok: true, messages: rows }) }],
@@ -553,9 +598,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       ttl_seconds: z.number().min(1).max(86400).optional().describe("Task TTL in seconds (default: 3600)"),
       network_id: z.string().max(200).optional().describe("Network scope"),
       parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. When the child task replies the hub will auto-chain the answer to the parent task's originator, so the user sees the final result even if the intermediate session ends."),
+      meta: z.any().optional().describe("Optional structured task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
     },
-    async ({ alias, task, priority, context, from_session: _fromIn, ttl_seconds, network_id: netId, parent_task_id: parentIn }) => { const from_session = defaultFrom(_fromIn);
+    async ({ alias, task, priority, context, from_session: _fromIn, ttl_seconds, network_id: netId, parent_task_id: parentIn, meta }) => { const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(netId);
+      const metaJson = normalizeMetaJson(meta);
       // Resolve parent_task_id: explicit > inferred (caller's most recent
       // delivered/started inbox task that's still open). Inference is the
       // safety net for when the LLM forgets to pass parent_task_id.
@@ -587,7 +634,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         }
       }
 
-      console.log(`[${ts()}] ${from_session} → send_task → ${alias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}`);
+      const canonical = resolveCanonicalAlias(effectiveNetId, alias);
+      const targetAlias = canonical.alias;
+      console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       // 事务：inbox + tasks 双写 + 触碰目标 session 的 task/updated_at（让
       // dashboard 在派任务一刻就反映出"任务已下发"，不再等 agent 的
@@ -595,23 +644,23 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // 报告冲突）。
       db.transaction(() => {
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, context, from_session, requires_response, network_id)
-           VALUES (?1, ?2, 'task', ?3, ?4, ?5, ?6, 'reply', ?7)`,
-          [id, alias, priority, task, context ?? null, from_session, effectiveNetId ?? null]
+          `INSERT INTO inbox (id, session_name, type, priority, content, context, from_session, requires_response, network_id, meta_json)
+           VALUES (?1, ?2, 'task', ?3, ?4, ?5, ?6, 'reply', ?7, ?8)`,
+          [id, targetAlias, priority, task, context ?? null, from_session, effectiveNetId ?? null, metaJson]
         );
         db.run(
-          `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id)
-           VALUES (?1, ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', ?6), ?7, ?8)`,
-          [id, from_session, alias, priority, task, `+${ttl_seconds || 3600} seconds`, effectiveNetId ?? null, parentTaskId]
+          `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id, meta_json)
+           VALUES (?1, ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', ?6), ?7, ?8, ?9)`,
+          [id, from_session, targetAlias, priority, task, `+${ttl_seconds || 3600} seconds`, effectiveNetId ?? null, parentTaskId, metaJson]
         );
-        const touchParams: any[] = [task.slice(0, 200), alias];
+        const touchParams: any[] = [task.slice(0, 200), targetAlias];
         let touchSql = "UPDATE sessions SET task = ?1, updated_at = datetime('now') WHERE alias = ?2";
         touchSql = addScope(touchSql, touchParams, effectiveNetId);
         db.run(touchSql, touchParams);
       });
-      logTaskEvent(id, null, "delivered", from_session, parentTaskId ? `→ ${alias} (parent=${parentTaskId.slice(0,8)})` : `→ ${alias}`);
+      logTaskEvent(id, null, "delivered", from_session, parentTaskId ? `→ ${targetAlias} (parent=${parentTaskId.slice(0,8)})` : `→ ${targetAlias}`);
 
-      const session = scopedSessionStatus(alias, effectiveNetId);
+      const session = scopedSessionStatus(targetAlias, effectiveNetId);
 
       // SSE push by alias.
       // The SSE channel is keyed by alias (subscribers connected to /events/<alias>),
@@ -620,11 +669,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // network_id=null but the sender supplied an explicit network_id (the
       // exact mismatch hit by Dashboard tasks). Push unconditionally; the
       // subscriber's own auth (ntok_) constrains who can listen.
-      const pendingParams: any[] = [alias];
+      const pendingParams: any[] = [targetAlias];
       let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       pendingSql = addScope(pendingSql, pendingParams, effectiveNetId);
       const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
-      pushEvent(alias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session }, effectiveNetId);
+      pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
 
       return {
         content: [
@@ -633,6 +682,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             text: JSON.stringify({
               ok: true,
               message_id: id,
+              ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
               session_status: session?.status ?? "unknown",
             }),
           },