@rubytech/create-realagent-code 0.1.573 → 0.1.575

package/payload/platform/plugins/admin/hooks/specialist-dispatch-gate.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# specialist-dispatch-gate — PreToolUse gate on every tool.
+#
+# An account's own specialists own their tools. This gate refuses the main
+# conversation a tool one of the account's authored cards declares, and names the
+# specialist to dispatch instead. It exists because skipped delegation writes no
+# record: an inline draft logs an ordinary success, so nothing in any log
+# separates "the clerk did it" from "the admin did it by hand". On one account
+# four authored clerks owned email, works orders, invoices and quotes while the
+# admin produced all of them inline for three days.
+#
+# Two narrowings, both load-bearing.
+#
+# Card axis — the account's OWN cards only. Provisioning copies every shipped
+# template into each account, and one of them declares roughly 130 tools
+# including the whole email, WhatsApp, calendar and browser surfaces, so reading
+# every card would refuse the admin nearly its entire seat. A card is the
+# account's own when its filename appears in none of the shipped roots. The
+# account's own plugin root is deliberately NOT one of those: a card filed there
+# is that account's durable copy, not something we ship.
+#
+# Tool axis — native tools are never gated. Every card declares some of Bash,
+# Read, Write and Edit, and refusing those would brick the seat. The NATIVE set
+# below mirrors CC_NATIVE_TOOLS in the session manager, which a bash hook cannot
+# import; the gate's own test compares the two sets rather than trusting them to
+# stay equal.
+#
+# Caller identity is `agent_type` from the hook envelope, which Claude Code sets
+# when a hook fires inside a subagent. A non-empty value exits 0 unconditionally:
+# this gate must never filter a subagent's tool surface, which is the failure an
+# inherited CLI deny produced when it stripped the writers from a specialist's
+# own frontmatter. The MAXY_SPECIALIST env is not usable — it is stamped only for
+# a specialist spawned as its own PTY process, and native Agent-tool subagents
+# inherit the admin process env.
+#
+# Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail OPEN on an
+# uninspectable envelope, and say so with op=degraded when the card set cannot be
+# read: failing open is fine, failing open silently is the fault. No task numbers
+# or internal refs in any operator-visible string.
+
+set -uo pipefail
+
+# No envelope (tty or empty stdin) → allow: cannot inspect, must not brick tools.
+if [ -t 0 ]; then exit 0; fi
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+# Prints nothing for an out-of-scope call, "block <specialist>" for a refusal, or
+# "degraded <reason>" when the card set could not be read.
+DECISION=$(INPUT="$INPUT" python3 - <<'PY' 2>/dev/null || true
+import os, json, re, sys, glob
+
+# Mirrors CC_NATIVE_TOOLS (claude-session-manager/src/specialist-drift.ts). A
+# card that declares these declares them for its own use; they are the admin's
+# too, and gating them would refuse the seat its own disk and shell.
+NATIVE = {
+    "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "LS", "Bash",
+    "BashOutput", "KillShell", "Skill", "WebSearch", "WebFetch", "Task",
+    "TodoWrite", "NotebookEdit", "NotebookRead", "AskUserQuestion",
+}
+
+try:
+    d = json.loads(os.environ["INPUT"])
+except Exception:
+    sys.exit(0)
+
+tool = (d.get("tool_name", "") or "").strip()
+if not tool or tool in NATIVE:
+    sys.exit(0)
+
+# A subagent is never filtered. This is the whole reason the gate can be broad:
+# it constrains one seat, not a tool surface.
+if (d.get("agent_type") or "").strip():
+    sys.exit(0)
+
+agents_dir = os.path.join(os.getcwd(), "specialists", "agents")
+platform_root = os.environ.get("PLATFORM_ROOT", "")
+
+shipped = set()
+try:
+    if platform_root:
+        for f in glob.glob(os.path.join(platform_root, "templates", "specialists", "agents", "*.md")):
+            shipped.add(os.path.basename(f))
+        for f in glob.glob(os.path.join(platform_root, "plugins", "*", "agents", "*.md")):
+            shipped.add(os.path.basename(f))
+        premium = os.path.join(os.path.dirname(platform_root), "premium-plugins")
+        for f in glob.glob(os.path.join(premium, "*", "agents", "*.md")):
+            shipped.add(os.path.basename(f))
+    if not os.path.isdir(agents_dir):
+        # An account with no specialists directory is normal, not degraded.
+        sys.exit(0)
+    cards = sorted(os.listdir(agents_dir))
+except Exception as err:
+    print("degraded %s" % type(err).__name__)
+    sys.exit(0)
+
+
+def fields(path):
+    """(name, tools) from a card's frontmatter, or None when there is none."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().split("\n")
+    except Exception:
+        return None
+    if not lines or lines[0].strip() != "---":
+        return None
+    name = tools = None
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        m = re.match(r'^name:\s*(.+?)\s*$', line)
+        if m:
+            name = m.group(1).strip().strip('"').strip("'")
+        m = re.match(r'^tools:\s*(.+?)\s*$', line)
+        if m:
+            tools = m.group(1)
+    return (name, tools)
+
+
+for filename in cards:
+    if not filename.endswith(".md"):
+        continue
+    if filename in shipped:
+        continue
+    got = fields(os.path.join(agents_dir, filename))
+    if not got:
+        continue
+    name, tools = got
+    if not name or not tools:
+        continue
+    # Match the tool itself, never a substring of a longer name.
+    for declared in tools.split(","):
+        declared = declared.strip()
+        if not declared or declared in NATIVE:
+            continue
+        if declared == tool:
+            print("block %s" % name)
+            sys.exit(0)
+PY
+)
+
+[ -z "$DECISION" ] && exit 0
+
+VERB=${DECISION%% *}
+ARG=${DECISION#* }
+
+if [ "$VERB" = "degraded" ]; then
+  echo "[specialist-gate] op=degraded reason=$ARG" >&2
+  exit 0
+fi
+
+ACCOUNT_ID8=$(basename "$PWD" | cut -c1-8)
+TOOL=$(printf '%s' "$INPUT" \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin).get("tool_name",""))' 2>/dev/null \
+  || echo "")
+
+echo "[specialist-gate] op=refuse account=$ACCOUNT_ID8 tool=$TOOL specialist=$ARG" >&2
+echo "Blocked: this tool belongs to your $ARG. Dispatch that specialist with the Agent tool and let it do the work — it holds the tool and the standards that go with it." >&2
+exit 2

package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.d.ts

@@ -0,0 +1,27 @@
+export type AdminBindVerdict = {
+    kind: "ok";
+    pin: string;
+} | {
+    kind: "nothing-to-set";
+} | {
+    kind: "bad-phone";
+} | {
+    kind: "bad-telegram";
+} | {
+    kind: "no-such-user";
+} | {
+    kind: "not-an-admin";
+};
+export declare function classifyAdminBind(input: {
+    userId: string;
+    phone?: string;
+    telegram?: string;
+    users: ReadonlyArray<{
+        userId: string;
+        pin: string;
+    }>;
+    admins: ReadonlyArray<{
+        userId: string;
+    }>;
+}): AdminBindVerdict;
+//# sourceMappingURL=admin-bind-classify.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-bind-classify.d.ts","sourceRoot":"","sources":["../src/admin-bind-classify.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAE7B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,MAAM,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3C,GAAG,gBAAgB,CAUnB"}

package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.js

@@ -0,0 +1,29 @@
+/**
+ * Task 2531 — the pure refusal policy for `admin-bind`, split from the IO
+ * wrapper for the same reason `resolve-admin-userid.ts` splits its picker: every
+ * refusal is then unit-testable without a filesystem, and the policy cannot
+ * drift from the tool that enforces it.
+ *
+ * Never infers a userId. `addAdminPhone` takes an account directory and a phone
+ * with no userId, which is exactly why it cannot write a binding: the allowlist
+ * knows a number, not a person. Binding runs the other way, so the caller names
+ * whom and an unknown userId is refused rather than guessed at.
+ */
+import { isE164, isTelegramChatId } from "./binding-validate.js";
+export function classifyAdminBind(input) {
+    if (input.phone === undefined && input.telegram === undefined)
+        return { kind: "nothing-to-set" };
+    if (input.phone !== undefined && !isE164(input.phone))
+        return { kind: "bad-phone" };
+    if (input.telegram !== undefined && !isTelegramChatId(input.telegram))
+        return { kind: "bad-telegram" };
+    const row = input.users.find(u => u.userId === input.userId);
+    if (!row)
+        return { kind: "no-such-user" };
+    if (!input.admins.some(a => a.userId === input.userId))
+        return { kind: "not-an-admin" };
+    // The existing hash, returned so the caller can route through writeAdminEntry
+    // (which requires a pin) without rotating the credential it is not touching.
+    return { kind: "ok", pin: row.pin };
+}
+//# sourceMappingURL=admin-bind-classify.js.map

package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-bind-classify.js","sourceRoot":"","sources":["../src/admin-bind-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAUjE,MAAM,UAAU,iBAAiB,CAAC,KAMjC;IACC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACjG,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACpF,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IACvG,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7D,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IACxF,8EAA8E;IAC9E,6EAA6E;IAC7E,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC;AACtC,CAAC"}

package/payload/platform/plugins/admin/mcp/dist/binding-validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Task 2531 — the two channel-binding shapes, in one place.
+ *
+ * Imported by `index.ts` (admin-add's own validation) and by
+ * `admin-bind-classify.ts` (admin-bind's refusal policy), so the tool and the
+ * policy cannot disagree about what a valid binding is. Two copies of a
+ * validation rule drift the same way two copies of the record type did.
+ */
+export declare function isE164(v: string): boolean;
+export declare function isTelegramChatId(v: string): boolean;
+//# sourceMappingURL=binding-validate.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/binding-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-validate.d.ts","sourceRoot":"","sources":["../src/binding-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzC;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/payload/platform/plugins/admin/mcp/dist/binding-validate.js

@@ -0,0 +1,20 @@
+/**
+ * Task 2531 — the two channel-binding shapes, in one place.
+ *
+ * Imported by `index.ts` (admin-add's own validation) and by
+ * `admin-bind-classify.ts` (admin-bind's refusal policy), so the tool and the
+ * policy cannot disagree about what a valid binding is. Two copies of a
+ * validation rule drift the same way two copies of the record type did.
+ */
+/** E.164, the same shape `config-persist.ts` enforces for `adminPhones`. */
+const E164 = /^\+[1-9]\d{1,14}$/;
+export function isE164(v) {
+    return E164.test(v);
+}
+/** A Telegram chat id is an integer. A group chat's is negative, so the leading
+ *  minus is legal and refusing it would reject a real binding. */
+const TG_CHAT_ID = /^-?\d+$/;
+export function isTelegramChatId(v) {
+    return TG_CHAT_ID.test(v);
+}
+//# sourceMappingURL=binding-validate.js.map

package/payload/platform/plugins/admin/mcp/dist/binding-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-validate.js","sourceRoot":"","sources":["../src/binding-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4EAA4E;AAC5E,MAAM,IAAI,GAAG,mBAAmB,CAAC;AAEjC,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACxC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC"}

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -9,6 +9,8 @@ import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSyn
 import { writeAdminEntry, removeAdminFromAccount, logUsersAudit, formatAuditRowIds } from "../../../../lib/admins-write/dist/index.js";
 import { setAccessPassword as setAccessPasswordHash, clearAccessPassword as clearAccessPasswordHash, accessPasswordCollides } from "../../../../lib/admin-access-password/dist/index.js";
 import { resolveCredentialTarget } from "./credential-identity.js";
+import { isE164, isTelegramChatId } from "./binding-validate.js";
+import { classifyAdminBind } from "./admin-bind-classify.js";
 import { embed } from "../../../../lib/embed-client/dist/index.js";
 import { requirePortEnv } from "../../../../lib/require-port-env/dist/index.js";
 import { deviceUrlBlock } from "../../../../lib/device-url/dist/index.js";
@@ -286,6 +288,32 @@ function readUsersJson() {
 function writeUsersJson(users) {
     writeFileSync(USERS_FILE, JSON.stringify(users, null, 2) + "\n", "utf-8");
 }
+/**
+ * Task 2531 — re-read users.json after a binding write and report what is
+ * actually on disk.
+ *
+ * "Called the writer" is not evidence the field landed. The whole reason a
+ * missing binding went unnoticed for the life of this install is that nothing
+ * ever checked the post-condition; the boot-time drift check reports it, but
+ * only on the NEXT boot. This closes that gap at the moment of the write.
+ * Returns the observed verdict and logs it either way.
+ */
+function verifyBindingWrite(tag, userId, want) {
+    let ok = false;
+    try {
+        const row = readUsersJson().find(u => u.userId === userId);
+        ok =
+            !!row &&
+                (want.phone === undefined || row.phone === want.phone) &&
+                (want.telegram === undefined || row.telegram === want.telegram);
+    }
+    catch {
+        ok = false;
+    }
+    const state = (v) => (v === undefined ? "absent" : "set");
+    console.error(`${tag} op=binding-write userId=${userId.slice(0, 8)} phone=${state(want.phone)} telegram=${state(want.telegram)} verified=${ok}`);
+    return ok;
+}
 function generateUniquePin(users, maxRetries = 10) {
     const existingPins = new Set(users.map(u => u.pin));
     for (let i = 0; i < maxRetries; i++) {
@@ -965,7 +993,9 @@ lifelineTool(server, "plugin-toggle-enabled", "Enable or disable a plugin in thi
 eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a device-level user entry (users.json) and adds them to this account's admins list (account.json). PIN must be at least 4 digits. If no PIN is provided, a unique 4-digit PIN is generated. Returns the userId and PIN to share with the new admin.\n\nIMPORTANT — retry behaviour: if the user already stated a specific PIN earlier in the conversation and a first admin-add call failed (e.g. tier cap reached, PIN collision), every retry MUST re-pass that PIN as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the user asked for.", {
     name: z.string().describe("Display name for the new admin (stored on the AdminUser node in Neo4j)."),
     pin: z.string().optional().describe("Optional PIN (minimum 4 digits). If omitted, a unique 4-digit PIN is generated."),
-}, async ({ name, pin: rawPin }) => {
+    phone: z.string().optional().describe("E.164 phone (e.g. +441234567890) binding this admin to their WhatsApp sender. Without it a WhatsApp turn from this person resolves to no admin. Settable later with admin-bind."),
+    telegram: z.string().optional().describe("Telegram chat id binding this admin to their Telegram chat (negative for a group). Without it a Telegram turn from this person resolves to no admin. Settable later with admin-bind."),
+}, async ({ name, pin: rawPin, phone, telegram }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("admin-add");
     const TAG = "[admin]";
@@ -984,6 +1014,16 @@ eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a
         process.stderr.write(`[admin-add] op=refused reason=no-name\n`);
         return { content: [{ type: "text", text: `${TAG} A real name is required (it cannot be blank or the placeholder "Owner").` }], isError: true };
     }
+    // Task 2531 — validate the bindings before any store write, so a malformed
+    // one cannot land a half-created admin.
+    if (phone !== undefined && !isE164(phone)) {
+        process.stderr.write(`[admin-add] op=refused reason=bad-phone\n`);
+        return { content: [{ type: "text", text: `${TAG} phone must be E.164, e.g. +441234567890.` }], isError: true };
+    }
+    if (telegram !== undefined && !isTelegramChatId(telegram)) {
+        process.stderr.write(`[admin-add] op=refused reason=bad-telegram\n`);
+        return { content: [{ type: "text", text: `${TAG} telegram must be a chat id (digits, optionally negative for a group).` }], isError: true };
+    }
     let users;
     try {
         users = readUsersJson();
@@ -1053,11 +1093,20 @@ eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a
         accountDir: getAccountDir(),
         caller: "admin-add",
         audit: { actor: callerUserId ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG },
+        // Task 2531 — the channel bindings, written by the same chokepoint as the
+        // PIN so a new admin can be born reachable on their own channels.
+        phone,
+        telegram,
     });
     console.error(`[admin-auth-store] action=add userId=${userIdShort} result=${authResult.usersJsonResult} store=users${authResult.usersError ? ` error=${authResult.usersError}` : ""}`);
     if (authResult.usersJsonResult !== "ok") {
         return { content: [{ type: "text", text: `${TAG} Failed to write users.json: ${authResult.usersError ?? "unknown error"}` }], isError: true };
     }
+    // Task 2531 — the observed post-condition, re-read from disk. A binding that
+    // silently failed to land looks identical to one that was never asked for.
+    if (phone !== undefined || telegram !== undefined) {
+        verifyBindingWrite("[admin-add]", userId, { phone, telegram });
+    }
     console.error(`[admin-auth-store] action=add userId=${userIdShort} result=${authResult.accountJsonResult} store=account${authResult.accountError ? ` error=${authResult.accountError}` : ""}`);
     if (authResult.accountJsonResult === "fail") {
         return { content: [{ type: "text", text: `${TAG} users.json updated; account.json write FAILED — manual reconciliation needed: ${authResult.accountError ?? "unknown error"}` }], isError: true };
@@ -1388,6 +1437,89 @@ eagerTool(server, "admin-update-pin", "Update an existing admin user's PIN. Defa
         content: [{ type: "text", text: `PIN updated${self ? "" : ` for userId ${userId}`}. The new PIN takes effect on the next login.` }],
     };
 });
+lifelineTool(server, "admin-bind", "Bind an admin to their channels by setting the phone and/or Telegram chat id on their users.json entry. This is what makes an inbound turn resolve AS that person: without it a WhatsApp or Telegram turn from them resolves to no admin. It does not affect where an answer goes, which is always the door the message arrived on. Defaults to the calling admin; pass userId (from admin-list) to bind someone else, which additionally requires confirm=true because a binding decides whose identity an inbound resolves to. Sets only the fields supplied; an omitted field is left untouched. A new admin can be born bound by passing the same fields to admin-add.", {
+    userId: z.string().optional().describe("The userId of the admin to bind. Defaults to the caller (the admin invoking this tool)."),
+    phone: z.string().optional().describe("E.164 phone (e.g. +441234567890) binding this admin to their WhatsApp sender."),
+    telegram: z.string().optional().describe("Telegram chat id binding this admin to their Telegram chat (negative for a group)."),
+    confirm: z.boolean().optional().describe("Required (true) only when userId names a DIFFERENT admin than the caller — confirms a deliberate cross-identity binding."),
+}, async ({ userId: targetUserId, phone, telegram, confirm }) => {
+    if (!ACCOUNT_ID)
+        return refuseNoAccount("admin-bind");
+    const TAG = "[admin-bind]";
+    // A binding decides which sender resolves AS this person, so it is a
+    // credential-class write: the same Task 1573 gate the PIN tools use. Without
+    // it any admin could point their own number at another admin's userId and
+    // have their inbound turns attributed to that person.
+    const callerUserId = verifiedCaller();
+    const resolved = resolveCredentialTarget({ explicitUserId: targetUserId, callerUserId, confirm });
+    if (!resolved.ok) {
+        console.error(`${TAG} result=refused reason=${resolved.error.split(":")[0]}`);
+        return { content: [{ type: "text", text: `${TAG} ${resolved.error}` }], isError: true };
+    }
+    const userId = resolved.target;
+    const label = userId.slice(0, 8);
+    const refuse = (reason, message) => {
+        console.error(`${TAG} userId=${label} result=refused reason=${reason}`);
+        return { content: [{ type: "text", text: `${TAG} ${message}` }], isError: true };
+    };
+    let users;
+    try {
+        users = readUsersJson();
+    }
+    catch (err) {
+        return refuse("users-json-read-failed", err instanceof Error ? err.message : String(err));
+    }
+    let admins;
+    try {
+        const config = await readAccountConfig();
+        admins = (config.admins ?? []);
+    }
+    catch (err) {
+        return refuse("account-config-read-failed", err instanceof Error ? err.message : String(err));
+    }
+    const verdict = classifyAdminBind({ userId, phone, telegram, users, admins });
+    if (verdict.kind !== "ok") {
+        const message = {
+            "nothing-to-set": "Supply phone, telegram, or both.",
+            "bad-phone": "phone must be E.164, e.g. +441234567890.",
+            "bad-telegram": "telegram must be a chat id (digits, optionally negative for a group).",
+            "no-such-user": `User ${userId} not found in users.json.`,
+            "not-an-admin": `User ${userId} is not an admin of this account.`,
+        };
+        return refuse(verdict.kind, message[verdict.kind]);
+    }
+    // The one chokepoint, same as admin-add. `verdict.pin` is the existing hash,
+    // so the credential is carried through untouched rather than rotated.
+    const result = writeAdminEntry({
+        userId,
+        pin: verdict.pin,
+        role: "admin",
+        usersFile: USERS_FILE,
+        accountDir: getAccountDir(),
+        caller: "admin-bind",
+        audit: {
+            actor: callerUserId ?? "unknown",
+            session: process.env.SESSION_NODE_ID,
+            logFile: USERS_AUDIT_LOG,
+            target: userId,
+            explicitUserId: resolved.isCrossIdentity,
+        },
+        phone,
+        telegram,
+    });
+    if (result.usersJsonResult !== "ok") {
+        return refuse("write-failed", `Failed to write users.json: ${result.usersError ?? "unknown error"}`);
+    }
+    if (!verifyBindingWrite(TAG, userId, { phone, telegram })) {
+        return refuse("not-verified", "The write reported success but the value is not on disk.");
+    }
+    const set = [phone !== undefined ? "phone" : null, telegram !== undefined ? "telegram" : null]
+        .filter(Boolean)
+        .join(" and ");
+    return {
+        content: [{ type: "text", text: `${TAG} Bound ${set} for ${label}. A turn from this person now reaches every channel they hold, not only the one it arrived on.` }],
+    };
+});
 lifelineTool(server, "agent-image", "Upload, update, or remove an agent's image. action=set: copy the file at filePath to the agent's assets directory and update config.json with image URL and shape. action=remove: delete the image file and clear the image fields from config.json. imageShape: 'circle' for avatars/icons, 'rounded' for logos.", {
     agentSlug: z.string().describe("Agent slug (e.g. 'coaching', 'sales')"),
     action: z.enum(["set", "remove"]),