@rubytech/create-maxy-code 0.1.573 → 0.1.574

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 and their answer reaches only the door it arrived on. 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 lets one answer reach every channel that person holds: without it a WhatsApp or Telegram turn resolves to no admin and the answer reaches only the door it 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"]),