@agent-team-foundation/first-tree-hub 0.7.1 → 0.8.0

package/dist/{core-C05B8FzH.mjs → core-BXS5ppsG.mjs}

@@ -1,9 +1,9 @@
 import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-CRDR6NwE.mjs";
-import { $ as updateAgentSchema, A as createOrganizationSchema, B as paginationQuerySchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as isRedactedEnvValue, G as sendToAgentSchema, H as runtimeStateMessageSchema, I as linkTaskChatSchema, J as sessionEventSchema$1, K as sessionCompletionMessageSchema, L as loginSchema, M as delegateFeishuUserSchema, N as dryRunAgentRuntimeConfigSchema, O as createChatSchema, P as inboxPollQuerySchema, Q as updateAgentRuntimeConfigSchema, R as messageSourceSchema$1, S as agentTypeSchema$1, T as createAdapterConfigSchema, U as selfServiceFeishuBotSchema, V as refreshTokenSchema, W as sendMessageSchema, X as taskListQuerySchema, Y as sessionStateMessageSchema, Z as updateAdapterConfigSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateMemberSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as wsAuthFrameSchema, j as createTaskSchema, k as createMemberSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateSystemConfigSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionEventMessageSchema, rt as updateTaskStatusSchema, s as AGENT_STATUSES, tt as updateOrganizationSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as connectTokenExchangeSchema, x as agentRuntimeConfigPayloadSchema$1, y as adminUpdateTaskSchema, z as notificationQuerySchema } from "./feishu-CJ08ntOD.mjs";
+import { $ as updateAgentRuntimeConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as updateAdapterConfigSchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionStateMessageSchema, Y as sessionEventSchema$1, Z as taskListQuerySchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as wsAuthFrameSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateTaskStatusSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateOrganizationSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateSystemConfigSchema, s as AGENT_STATUSES, tt as updateMemberSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-D9JkMZnU.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { ZodError, z } from "zod";
-import "yaml";
+import { stringify } from "yaml";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, hostname, platform, userInfo } from "node:os";
 import { EventEmitter } from "node:events";
@@ -198,6 +198,19 @@ z.object({
 	branch: z.string().nullable()
 });
 /**
+* Server → client WebSocket frame announcing that an agent has just been
+* pinned to the connected client (either created with `clientId` or bound via
+* PATCH NULL → ID). The client can auto-register a local config from this so
+* the operator doesn't have to run `first-tree-hub agent add` manually.
+*/
+const agentPinnedMessageSchema = z.object({
+	type: z.literal("agent:pinned"),
+	agentId: z.string(),
+	name: z.string().nullable(),
+	displayName: z.string().nullable(),
+	agentType: agentTypeSchema
+});
+/**
 * Agent runtime configuration — M1 (Claude Code only).
 *
 * Defines the 5 user-tunable field groups that the Hub centrally manages
@@ -1165,6 +1178,11 @@ var ClientConnection = class extends EventEmitter {
 			this.emit("agent:unbound", agentId);
 			return;
 		}
+		if (type === "agent:pinned") {
+			const parsed = agentPinnedMessageSchema.safeParse(msg);
+			if (parsed.success) this.emit("agent:pinned", parsed.data);
+			return;
+		}
 		if (type === "agent:force_disconnect") {
 			const agentId = msg.agentId;
 			if (agentId && this.boundAgents.has(agentId)) {
@@ -1493,6 +1511,451 @@ echo "long message body" | first-tree-hub agent send <agentId>
 For content with quotes, \`$\`, backticks, or newlines, prefer stdin to avoid shell escaping issues.
 `;
 }
+const DEFAULT_CLONE_TIMEOUT_MS = 300 * 1e3;
+const FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
+const SESSION_BRANCH_PREFIX = "hub-session";
+function hashUrl(url) {
+	return createHash("sha256").update(url).digest("hex").slice(0, 32);
+}
+function shortHash(input) {
+	return createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+function deriveSessionBranchName(sessionKey, url) {
+	return `${SESSION_BRANCH_PREFIX}-${shortHash(sessionKey)}-${shortHash(url)}`;
+}
+/**
+* A value is SHA-like when it's a 7–40 character hex string. Used to decide
+* whether `ref` should be resolved via the remote namespace (branch name) or
+* used as-is (commit hash).
+*/
+function looksLikeCommitSha(ref) {
+	return /^[0-9a-f]{7,40}$/i.test(ref);
+}
+function createGitMirrorManager(opts) {
+	const mirrorsRoot = join(opts.dataDir, "git-mirrors");
+	const cloneTimeoutMs = opts.cloneTimeoutMs ?? Number(process.env.FIRST_TREE_HUB_GIT_CLONE_TIMEOUT_MS ?? DEFAULT_CLONE_TIMEOUT_MS);
+	const log = opts.log ?? (() => {});
+	const urlLocks = /* @__PURE__ */ new Map();
+	function withUrlLock(url, op) {
+		const key = hashUrl(url);
+		const next = (urlLocks.get(key) ?? Promise.resolve()).then(op, op);
+		urlLocks.set(key, next);
+		next.then(() => {
+			if (urlLocks.get(key) === next) urlLocks.delete(key);
+		}, () => {
+			if (urlLocks.get(key) === next) urlLocks.delete(key);
+		});
+		return next;
+	}
+	function mirrorDir(url) {
+		return join(mirrorsRoot, hashUrl(url));
+	}
+	async function git(args, cwd, timeoutMs, env) {
+		const start = Date.now();
+		return await new Promise((resolveExec, rejectExec) => {
+			const proc = spawn("git", args, {
+				cwd: cwd ?? void 0,
+				env: env ?? process.env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			let stdout = "";
+			let stderr = "";
+			proc.stdout.on("data", (d) => {
+				stdout += String(d);
+			});
+			proc.stderr.on("data", (d) => {
+				stderr += String(d);
+			});
+			const timer = setTimeout(() => {
+				proc.kill("SIGKILL");
+				rejectExec(new GitMirrorTimeoutError(`git ${args.join(" ")} timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			proc.on("error", (err) => {
+				clearTimeout(timer);
+				rejectExec(err);
+			});
+			proc.on("close", (code) => {
+				clearTimeout(timer);
+				const elapsedMs = Date.now() - start;
+				if (code === 0) resolveExec({
+					stdout,
+					stderr,
+					elapsedMs
+				});
+				else rejectExec(new GitMirrorError(`git ${args.join(" ")} exited with code ${code}: ${stderr.slice(0, 1024)}`));
+			});
+		});
+	}
+	async function gitOk(args, cwd, timeoutMs) {
+		try {
+			await git(args, cwd, timeoutMs);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Bring the mirror's config to the invariant expected by this module:
+	* fetch refspec = `+refs/heads/*:refs/remotes/origin/*`, `remote.origin.mirror`
+	* absent, `refs/remotes/origin/HEAD` resolvable.
+	*
+	* Called from `ensureMirror` on every invocation — both the fresh-clone path
+	* (ensures our own bootstrap wrote the right values) and the pre-existing
+	* mirror path (repairs drift from the legacy `--mirror` config).
+	*/
+	async function assertMirrorConfig(mirrorPath, url) {
+		let migrated = false;
+		let currentFetch = "";
+		try {
+			const { stdout } = await git([
+				"config",
+				"--get-all",
+				"remote.origin.fetch"
+			], mirrorPath, 1e4);
+			currentFetch = stdout.trim();
+		} catch {
+			currentFetch = "";
+		}
+		if (currentFetch !== FETCH_REFSPEC) {
+			await git([
+				"config",
+				"--replace-all",
+				"remote.origin.fetch",
+				FETCH_REFSPEC
+			], mirrorPath, 1e4);
+			migrated = true;
+		}
+		if (await gitOk([
+			"config",
+			"--get",
+			"remote.origin.mirror"
+		], mirrorPath, 1e4)) {
+			await git([
+				"config",
+				"--unset-all",
+				"remote.origin.mirror"
+			], mirrorPath, 1e4);
+			migrated = true;
+		}
+		try {
+			const { stdout } = await git([
+				"config",
+				"--get",
+				"remote.origin.url"
+			], mirrorPath, 1e4);
+			if (stdout.trim() !== url) {
+				await git([
+					"config",
+					"--replace-all",
+					"remote.origin.url",
+					url
+				], mirrorPath, 1e4);
+				migrated = true;
+			}
+		} catch {
+			await git([
+				"remote",
+				"add",
+				"origin",
+				url
+			], mirrorPath, 1e4);
+			migrated = true;
+		}
+		if (migrated) {
+			await git([
+				"fetch",
+				"--prune",
+				"origin"
+			], mirrorPath, cloneTimeoutMs);
+			await gitOk([
+				"remote",
+				"set-head",
+				"origin",
+				"--auto"
+			], mirrorPath, 3e4);
+			log("mirrorConfigMigrated", { gitUrl: url });
+		}
+		return { migrated };
+	}
+	/**
+	* Bootstrap a fresh mirror at `mirrorPath`. Uses `git init --bare` +
+	* manual remote setup rather than `git clone --mirror` / `git clone --bare`,
+	* so we never transiently have the mirror configured to force-write
+	* `refs/heads/*` on fetch.
+	*/
+	async function bootstrapMirror(mirrorPath, url) {
+		mkdirSync(dirname(mirrorPath), { recursive: true });
+		await git([
+			"init",
+			"--bare",
+			mirrorPath
+		], null, cloneTimeoutMs);
+		await git([
+			"remote",
+			"add",
+			"origin",
+			url
+		], mirrorPath, 1e4);
+		await git([
+			"config",
+			"--replace-all",
+			"remote.origin.fetch",
+			FETCH_REFSPEC
+		], mirrorPath, 1e4);
+		await git([
+			"fetch",
+			"--prune",
+			"origin"
+		], mirrorPath, cloneTimeoutMs);
+		await gitOk([
+			"remote",
+			"set-head",
+			"origin",
+			"--auto"
+		], mirrorPath, 3e4);
+	}
+	async function branchExists(mirrorPath, branchName) {
+		return await gitOk([
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`refs/heads/${branchName}`
+		], mirrorPath, 1e4);
+	}
+	/**
+	* Resolve the commit-ish to base a new session branch on.
+	*
+	* - explicit SHA → use as-is
+	* - explicit branch name → prefer `refs/remotes/origin/<ref>`, fall back to
+	*   a literal SHA resolution in case the caller handed us a short commit
+	* - `ref` absent → `refs/remotes/origin/HEAD`
+	*/
+	async function resolveBase(mirrorPath, ref) {
+		if (!ref) {
+			if (await gitOk([
+				"rev-parse",
+				"--verify",
+				"--quiet",
+				"refs/remotes/origin/HEAD"
+			], mirrorPath, 1e4)) return "refs/remotes/origin/HEAD";
+			throw new GitMirrorError("Cannot resolve default branch: refs/remotes/origin/HEAD is missing. Re-run with an explicit `ref`.");
+		}
+		if (looksLikeCommitSha(ref)) {
+			if (await gitOk([
+				"cat-file",
+				"-e",
+				ref
+			], mirrorPath, 1e4)) return ref;
+		}
+		const remoteRef = `refs/remotes/origin/${ref}`;
+		if (await gitOk([
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			remoteRef
+		], mirrorPath, 1e4)) return remoteRef;
+		return ref;
+	}
+	return {
+		get mirrorsRoot() {
+			return mirrorsRoot;
+		},
+		ensureMirror(url) {
+			return withUrlLock(url, async () => {
+				mkdirSync(mirrorsRoot, { recursive: true });
+				const path = mirrorDir(url);
+				if (existsSync(join(path, "HEAD"))) {
+					const { migrated } = await assertMirrorConfig(path, url);
+					if (migrated) {}
+					return {
+						mirrorPath: path,
+						elapsedMs: 0,
+						cloned: false
+					};
+				}
+				const start = Date.now();
+				try {
+					await bootstrapMirror(path, url);
+					const elapsedMs = Date.now() - start;
+					log("ensureMirror", {
+						gitUrl: url,
+						elapsedMs,
+						cloned: true
+					});
+					return {
+						mirrorPath: path,
+						elapsedMs,
+						cloned: true
+					};
+				} catch (err) {
+					if (err instanceof GitMirrorTimeoutError) log("mirrorCloneTimeout", {
+						gitUrl: url,
+						timeoutMs: cloneTimeoutMs,
+						elapsedMs: cloneTimeoutMs
+					});
+					if (existsSync(path)) rmSync(path, {
+						recursive: true,
+						force: true
+					});
+					throw err;
+				}
+			});
+		},
+		fetchMirror(url) {
+			return withUrlLock(url, async () => {
+				const path = mirrorDir(url);
+				if (!existsSync(join(path, "HEAD"))) throw new GitMirrorError(`Cannot fetch — no mirror exists for "${url}"`);
+				try {
+					const { elapsedMs } = await git([
+						"fetch",
+						"--prune",
+						"origin"
+					], path, cloneTimeoutMs);
+					return { elapsedMs };
+				} catch (err) {
+					log("mirrorFetchFailed", {
+						gitUrl: url,
+						errorCode: err instanceof GitMirrorError ? "git-failed" : "unknown",
+						stderr: err instanceof Error ? err.message.slice(0, 1024) : String(err).slice(0, 1024)
+					});
+					throw err;
+				}
+			});
+		},
+		createWorktree({ url, ref, targetPath, sessionKey }) {
+			return withUrlLock(url, async () => {
+				const mirror = mirrorDir(url);
+				if (!existsSync(join(mirror, "HEAD"))) throw new GitMirrorError(`Cannot create worktree — no mirror exists for "${url}"`);
+				const absTarget = resolve(targetPath);
+				const branchName = deriveSessionBranchName(sessionKey, url);
+				if (existsSync(absTarget) && !isHubManagedWorktree(absTarget)) {
+					log("worktreeCreateConflict", {
+						gitUrl: url,
+						targetPath: absTarget,
+						occupantKind: classifyOccupant(absTarget)
+					});
+					throw new GitMirrorWorktreeConflictError(`Worktree target "${absTarget}" is already occupied by ${classifyOccupant(absTarget)} — aborting (D13)`);
+				}
+				const pathExists = existsSync(absTarget);
+				const hasBranch = await branchExists(mirror, branchName);
+				mkdirSync(dirname(absTarget), { recursive: true });
+				if (pathExists && hasBranch) {} else if (pathExists && !hasBranch) throw new GitMirrorError(`Worktree directory "${absTarget}" exists as a Hub worktree but the expected session branch "${branchName}" is missing in the mirror — manual cleanup required`);
+				else if (!pathExists && hasBranch) await git([
+					"worktree",
+					"add",
+					absTarget,
+					branchName
+				], mirror, cloneTimeoutMs);
+				else await git([
+					"worktree",
+					"add",
+					"-b",
+					branchName,
+					absTarget,
+					await resolveBase(mirror, ref)
+				], mirror, cloneTimeoutMs);
+				return {
+					worktreePath: absTarget,
+					headCommit: (await git(["rev-parse", "HEAD"], absTarget, 3e4)).stdout.trim(),
+					branchName
+				};
+			});
+		},
+		removeWorktree({ url, path, branchName }) {
+			return withUrlLock(url, async () => {
+				const absTarget = resolve(path);
+				const mirror = mirrorDir(url);
+				if (!isBareRepo(mirror)) {
+					if (existsSync(absTarget)) rmSync(absTarget, {
+						recursive: true,
+						force: true
+					});
+					return;
+				}
+				if (existsSync(absTarget)) await gitOk([
+					"worktree",
+					"remove",
+					"--force",
+					absTarget
+				], mirror, 3e4);
+				else await gitOk(["worktree", "prune"], mirror, 3e4);
+				if (existsSync(absTarget)) rmSync(absTarget, {
+					recursive: true,
+					force: true
+				});
+				if (await branchExists(mirror, branchName)) await gitOk([
+					"branch",
+					"-D",
+					branchName
+				], mirror, 1e4);
+			});
+		},
+		async gcMirrors(stillReferencedUrls) {
+			if (!existsSync(mirrorsRoot)) return { removed: [] };
+			const wantedHashes = new Set([...stillReferencedUrls].map(hashUrl));
+			const removed = [];
+			for (const entry of readdirSync(mirrorsRoot)) {
+				if (wantedHashes.has(entry)) continue;
+				const path = join(mirrorsRoot, entry);
+				if (!isBareRepo(path)) continue;
+				rmSync(path, {
+					recursive: true,
+					force: true
+				});
+				removed.push(entry);
+			}
+			return { removed };
+		}
+	};
+}
+function isBareRepo(p) {
+	return existsSync(join(p, "HEAD")) && existsSync(join(p, "objects"));
+}
+function isHubManagedWorktree(p) {
+	const gitMarker = join(p, ".git");
+	if (!existsSync(gitMarker)) return false;
+	try {
+		return statSync(gitMarker).isFile();
+	} catch {
+		return false;
+	}
+}
+function classifyOccupant(p) {
+	try {
+		const stat = statSync(p);
+		if (stat.isSymbolicLink()) return "symlink";
+		if (stat.isDirectory()) {
+			if (existsSync(join(p, ".git"))) return "git-repo";
+			return "directory";
+		}
+		if (stat.isFile()) return "file";
+		return "other";
+	} catch {
+		return "unknown";
+	}
+}
+var GitMirrorError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GitMirrorError";
+	}
+};
+var GitMirrorTimeoutError = class extends GitMirrorError {
+	constructor(message) {
+		super(message);
+		this.name = "GitMirrorTimeoutError";
+	}
+};
+var GitMirrorWorktreeConflictError = class extends GitMirrorError {
+	constructor(message) {
+		super(message);
+		this.name = "GitMirrorWorktreeConflictError";
+	}
+};
 /**
 * InputController — push-based async iterable bridge.
 *
@@ -1741,7 +2204,7 @@ const createClaudeCodeHandler = (config) => {
 	let appliedConfigVersion = 0;
 	let appliedModel = "";
 	let appliedPayload = null;
-	/** Worktree paths materialised for this session — removed on shutdown. */
+	/** Worktrees materialised for this session — each entry removed on shutdown. */
 	const ownedWorktrees = [];
 	function toSDKUserMessage(message, sessionId) {
 		const rawContent = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
@@ -1965,28 +2428,37 @@ const createClaudeCodeHandler = (config) => {
 			await gitMirrorManager.fetchMirror(repo.url);
 			if (existsSync(targetPath) && isHubWorktreeMarker(targetPath)) {
 				sessionCtx.log(`Git: reusing existing worktree at ${localPath}`);
-				ownedWorktrees.push(targetPath);
+				ownedWorktrees.push({
+					url: repo.url,
+					path: targetPath,
+					branchName: deriveSessionBranchName(sessionCtx.chatId, repo.url)
+				});
 				continue;
 			}
-			const { headCommit } = await gitMirrorManager.createWorktree({
+			const { headCommit, branchName } = await gitMirrorManager.createWorktree({
 				url: repo.url,
 				ref: repo.ref,
-				targetPath
+				targetPath,
+				sessionKey: sessionCtx.chatId
+			});
+			ownedWorktrees.push({
+				url: repo.url,
+				path: targetPath,
+				branchName
 			});
-			ownedWorktrees.push(targetPath);
-			sessionCtx.log(`Git: worktree at ${localPath} @ ${headCommit.slice(0, 7)}`);
+			sessionCtx.log(`Git: worktree at ${localPath} @ ${headCommit.slice(0, 7)} on ${branchName}`);
 		}
 	}
 	/** Tear down all worktrees this session owns; best-effort. */
 	async function cleanupGitWorktrees(sessionCtx) {
 		if (!gitMirrorManager) return;
 		while (ownedWorktrees.length > 0) {
-			const path = ownedWorktrees.pop();
-			if (!path) continue;
+			const entry = ownedWorktrees.pop();
+			if (!entry) continue;
 			try {
-				await gitMirrorManager.removeWorktree(path);
+				await gitMirrorManager.removeWorktree(entry);
 			} catch (err) {
-				sessionCtx.log(`Git: removeWorktree(${path}) failed — ${err instanceof Error ? err.message : String(err)}`);
+				sessionCtx.log(`Git: removeWorktree(${entry.path}) failed — ${err instanceof Error ? err.message : String(err)}`);
 			}
 		}
 	}
@@ -2200,226 +2672,6 @@ function createAgentConfigCache(opts) {
 		}
 	};
 }
-const DEFAULT_CLONE_TIMEOUT_MS = 300 * 1e3;
-function hashUrl(url) {
-	return createHash("sha256").update(url).digest("hex").slice(0, 32);
-}
-function createGitMirrorManager(opts) {
-	const mirrorsRoot = join(opts.dataDir, "git-mirrors");
-	const cloneTimeoutMs = opts.cloneTimeoutMs ?? Number(process.env.FIRST_TREE_HUB_GIT_CLONE_TIMEOUT_MS ?? DEFAULT_CLONE_TIMEOUT_MS);
-	const log = opts.log ?? (() => {});
-	function mirrorDir(url) {
-		return join(mirrorsRoot, hashUrl(url));
-	}
-	async function git(args, cwd, timeoutMs, env) {
-		const start = Date.now();
-		return await new Promise((resolveExec, rejectExec) => {
-			const proc = spawn("git", args, {
-				cwd: cwd ?? void 0,
-				env: env ?? process.env,
-				stdio: [
-					"ignore",
-					"pipe",
-					"pipe"
-				]
-			});
-			let stdout = "";
-			let stderr = "";
-			proc.stdout.on("data", (d) => {
-				stdout += String(d);
-			});
-			proc.stderr.on("data", (d) => {
-				stderr += String(d);
-			});
-			const timer = setTimeout(() => {
-				proc.kill("SIGKILL");
-				rejectExec(new GitMirrorTimeoutError(`git ${args.join(" ")} timed out after ${timeoutMs}ms`));
-			}, timeoutMs);
-			proc.on("error", (err) => {
-				clearTimeout(timer);
-				rejectExec(err);
-			});
-			proc.on("close", (code) => {
-				clearTimeout(timer);
-				const elapsedMs = Date.now() - start;
-				if (code === 0) resolveExec({
-					stdout,
-					stderr,
-					elapsedMs
-				});
-				else rejectExec(new GitMirrorError(`git ${args.join(" ")} exited with code ${code}: ${stderr.slice(0, 1024)}`));
-			});
-		});
-	}
-	return {
-		get mirrorsRoot() {
-			return mirrorsRoot;
-		},
-		async ensureMirror(url) {
-			mkdirSync(mirrorsRoot, { recursive: true });
-			const path = mirrorDir(url);
-			if (existsSync(join(path, "HEAD"))) return {
-				mirrorPath: path,
-				elapsedMs: 0,
-				cloned: false
-			};
-			try {
-				const { elapsedMs } = await git([
-					"clone",
-					"--mirror",
-					url,
-					path
-				], null, cloneTimeoutMs);
-				log("ensureMirror", {
-					gitUrl: url,
-					elapsedMs,
-					cloned: true
-				});
-				return {
-					mirrorPath: path,
-					elapsedMs,
-					cloned: true
-				};
-			} catch (err) {
-				if (err instanceof GitMirrorTimeoutError) log("mirrorCloneTimeout", {
-					gitUrl: url,
-					timeoutMs: cloneTimeoutMs,
-					elapsedMs: cloneTimeoutMs
-				});
-				if (existsSync(path)) rmSync(path, {
-					recursive: true,
-					force: true
-				});
-				throw err;
-			}
-		},
-		async fetchMirror(url) {
-			const path = mirrorDir(url);
-			if (!existsSync(join(path, "HEAD"))) throw new GitMirrorError(`Cannot fetch — no mirror exists for "${url}"`);
-			try {
-				const { elapsedMs } = await git(["fetch", "--prune"], path, cloneTimeoutMs);
-				return { elapsedMs };
-			} catch (err) {
-				log("mirrorFetchFailed", {
-					gitUrl: url,
-					errorCode: err instanceof GitMirrorError ? "git-failed" : "unknown",
-					stderr: err instanceof Error ? err.message.slice(0, 1024) : String(err).slice(0, 1024)
-				});
-				throw err;
-			}
-		},
-		async createWorktree({ url, ref, targetPath }) {
-			const mirror = mirrorDir(url);
-			if (!existsSync(join(mirror, "HEAD"))) throw new GitMirrorError(`Cannot create worktree — no mirror exists for "${url}"`);
-			const absTarget = resolve(targetPath);
-			if (existsSync(absTarget) && !isHubManagedWorktree(absTarget)) {
-				log("worktreeCreateConflict", {
-					gitUrl: url,
-					targetPath: absTarget,
-					occupantKind: classifyOccupant(absTarget)
-				});
-				throw new GitMirrorWorktreeConflictError(`Worktree target "${absTarget}" is already occupied by ${classifyOccupant(absTarget)} — aborting (D13)`);
-			}
-			mkdirSync(dirname(absTarget), { recursive: true });
-			const args = [
-				"worktree",
-				"add",
-				"--detach",
-				absTarget
-			];
-			if (ref) args.push(ref);
-			await git(args, mirror, cloneTimeoutMs);
-			return {
-				worktreePath: absTarget,
-				headCommit: (await git(["rev-parse", "HEAD"], absTarget, 3e4)).stdout.trim()
-			};
-		},
-		async removeWorktree(path) {
-			const absTarget = resolve(path);
-			if (!existsSync(absTarget)) return;
-			if (!existsSync(mirrorsRoot)) return;
-			let removed = false;
-			for (const entry of readdirSync(mirrorsRoot)) {
-				const mirror = join(mirrorsRoot, entry);
-				if (!isBareRepo(mirror)) continue;
-				try {
-					await git([
-						"worktree",
-						"remove",
-						"--force",
-						absTarget
-					], mirror, 3e4);
-					removed = true;
-					break;
-				} catch {}
-			}
-			if (!removed && existsSync(absTarget)) rmSync(absTarget, {
-				recursive: true,
-				force: true
-			});
-		},
-		async gcMirrors(stillReferencedUrls) {
-			if (!existsSync(mirrorsRoot)) return { removed: [] };
-			const wantedHashes = new Set([...stillReferencedUrls].map(hashUrl));
-			const removed = [];
-			for (const entry of readdirSync(mirrorsRoot)) {
-				if (wantedHashes.has(entry)) continue;
-				const path = join(mirrorsRoot, entry);
-				if (!isBareRepo(path)) continue;
-				rmSync(path, {
-					recursive: true,
-					force: true
-				});
-				removed.push(entry);
-			}
-			return { removed };
-		}
-	};
-}
-function isBareRepo(p) {
-	return existsSync(join(p, "HEAD")) && existsSync(join(p, "objects"));
-}
-function isHubManagedWorktree(p) {
-	const gitMarker = join(p, ".git");
-	if (!existsSync(gitMarker)) return false;
-	try {
-		return statSync(gitMarker).isFile();
-	} catch {
-		return false;
-	}
-}
-function classifyOccupant(p) {
-	try {
-		const stat = statSync(p);
-		if (stat.isSymbolicLink()) return "symlink";
-		if (stat.isDirectory()) {
-			if (existsSync(join(p, ".git"))) return "git-repo";
-			return "directory";
-		}
-		if (stat.isFile()) return "file";
-		return "other";
-	} catch {
-		return "unknown";
-	}
-}
-var GitMirrorError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "GitMirrorError";
-	}
-};
-var GitMirrorTimeoutError = class extends GitMirrorError {
-	constructor(message) {
-		super(message);
-		this.name = "GitMirrorTimeoutError";
-	}
-};
-var GitMirrorWorktreeConflictError = class extends GitMirrorError {
-	constructor(message) {
-		super(message);
-		this.name = "GitMirrorWorktreeConflictError";
-	}
-};
 /**
 * Deduplicator — bounded set of recently seen IDs.
 *
@@ -3211,8 +3463,15 @@ var ClientRuntime = class {
 	connection;
 	agents = [];
 	agentNames = /* @__PURE__ */ new Set();
+	agentIds = /* @__PURE__ */ new Set();
 	watcher = null;
 	debounceTimer = null;
+	/**
+	* Directory we write auto-registered agent configs into (same path that
+	* `first-tree-hub agent add` uses). Set by `watchAgentsDir` so the
+	* `agent:pinned` handler knows where to materialise new configs.
+	*/
+	agentsDir = null;
 	constructor(serverUrl, clientId) {
 		this.serverUrl = serverUrl;
 		this.connection = new ClientConnection({
@@ -3224,6 +3483,9 @@ var ClientRuntime = class {
 		this.connection.on("auth:expired", () => {
 			process.stderr.write("  ⚠️  Access token expired — reconnecting after refresh...\n");
 		});
+		this.connection.on("agent:pinned", (message) => {
+			this.handleAgentPinned(message);
+		});
 	}
 	addAgent(name, config) {
 		if (this.agentNames.has(name)) return;
@@ -3246,6 +3508,7 @@ var ClientRuntime = class {
 			slot
 		});
 		this.agentNames.add(name);
+		this.agentIds.add(config.agentId);
 	}
 	async start() {
 		await this.connection.connect();
@@ -3268,6 +3531,7 @@ var ClientRuntime = class {
 		process.stderr.write(`\n  ${connected} agent(s) running. Press Ctrl+C to stop.\n`);
 	}
 	watchAgentsDir(agentsDir) {
+		this.agentsDir = agentsDir;
 		if (this.watcher) return;
 		if (!existsSync(agentsDir)) return;
 		this.watcher = watch(agentsDir, { recursive: true }, () => {
@@ -3301,12 +3565,68 @@ var ClientRuntime = class {
 			});
 			for (const [name, config] of all) {
 				if (this.agentNames.has(name)) continue;
+				if (this.agentIds.has(config.agentId)) continue;
 				process.stderr.write(`\n  New agent detected: ${name}\n`);
 				this.addAgent(name, config);
 				this.startAgent(name);
 			}
 		} catch {}
 	}
+	/**
+	* React to an `agent:pinned` server push by writing the local config file
+	* (same shape `first-tree-hub agent add` produces) and scheduling the new
+	* slot — so the operator doesn't have to run `agent add` manually after
+	* creating an agent from the admin UI or API.
+	*/
+	handleAgentPinned(message) {
+		if (this.agentIds.has(message.agentId)) return;
+		if (!this.agentsDir) {
+			process.stderr.write(`  \u26A0\uFE0F  Agent pinned (${message.agentId}) but no agents dir set — cannot auto-register.\n`);
+			return;
+		}
+		const localName = this.pickLocalName(message);
+		const agentDir = join(this.agentsDir, localName);
+		try {
+			mkdirSync(agentDir, {
+				recursive: true,
+				mode: 448
+			});
+			const yaml = stringify({
+				agentId: message.agentId,
+				runtime: "claude-code"
+			});
+			writeFileSync(join(agentDir, "agent.yaml"), yaml, { mode: 384 });
+			process.stderr.write(`  \u2713 Auto-added agent "${localName}" (${message.agentId}) from server push.\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`  \u2717 Failed to auto-add agent "${localName}": ${msg}\n`);
+			return;
+		}
+		this.scanForNewAgents(this.agentsDir);
+	}
+	/**
+	* Choose the directory name under `agents/<name>/agent.yaml` for an agent
+	* pushed by the server. Prefer the server-side `name` when set and not
+	* already claimed; otherwise fall back to a UUID-derived name with a numeric
+	* suffix on collision.
+	*
+	* UUID v7 packs the unix-ms timestamp in the high bits, so two agents
+	* created in the same millisecond share the first 8 hex chars. Take 16 chars
+	* (the full ms-timestamp segment plus the random tail) to make accidental
+	* collisions astronomically unlikely, and re-check `agentNames` so even an
+	* adversarial collision falls through to a `-2`, `-3`, … suffix.
+	*/
+	pickLocalName(message) {
+		const preferred = message.name;
+		if (preferred && !this.agentNames.has(preferred)) return preferred;
+		const base = `agent-${message.agentId.replace(/[^a-z0-9]/gi, "").slice(0, 16).toLowerCase()}`;
+		if (!this.agentNames.has(base)) return base;
+		for (let suffix = 2; suffix < 1e3; suffix++) {
+			const candidate = `${base}-${suffix}`;
+			if (!this.agentNames.has(candidate)) return candidate;
+		}
+		return `agent-${message.agentId.replace(/[^a-z0-9]/gi, "").toLowerCase()}`;
+	}
 	startAgent(name) {
 		const entry = this.agents.find((a) => a.name === name);
 		if (!entry) return;
@@ -3972,7 +4292,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-CJ08ntOD.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-D9JkMZnU.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) process.stderr.write(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -4113,7 +4433,7 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
-//#region ../server/dist/app-CWKBBGod.mjs
+//#region ../server/dist/app-TMhTLXuz.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -5713,6 +6033,23 @@ async function getClient(db, clientId) {
 	const [row] = await db.select().from(clients).where(eq(clients.id, clientId)).limit(1);
 	return row ?? null;
 }
+/**
+* List the active agents currently pinned to a client. Used by the WS
+* registration handshake to backfill `agent:pinned` notifications missed while
+* the client was offline — without it, an admin who pinned an agent during a
+* client outage would still need a manual `first-tree-hub agent add`.
+*
+* Excludes soft-deleted agents (status = "deleted"). Human agents are
+* naturally excluded by the `clientId` filter — they never carry a clientId.
+*/
+async function listActiveAgentsPinnedToClient(db, clientId) {
+	return db.select({
+		uuid: agents.uuid,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type
+	}).from(agents).where(and(eq(agents.clientId, clientId), ne(agents.status, "deleted")));
+}
 async function listClients(db, userId) {
 	const rows = await db.select().from(clients).where(eq(clients.userId, userId));
 	const counts = await db.select({
@@ -5850,6 +6187,13 @@ function removeClientConnection(clientId, ws) {
 	clientConnections.delete(clientId);
 	return agentIds;
 }
+/** Send a message to a client's WebSocket. Returns true if delivered. */
+function sendToClient(clientId, message) {
+	const entry = clientConnections.get(clientId);
+	if (!entry || entry.ws.readyState !== 1) return false;
+	entry.ws.send(JSON.stringify(message));
+	return true;
+}
 /** Send a message to a specific agent via its client's WebSocket. Returns true if delivered. */
 function sendToAgent$1(agentId, message) {
 	const clientId = agentToClient.get(agentId);
@@ -6116,6 +6460,34 @@ function notifyRecipients(notifier, recipients, messageId) {
 	for (const inboxId of recipients) notifier.notify(inboxId, messageId).catch(() => {});
 }
 async function adminAgentRoutes(app) {
+	/**
+	* Push an `agent:pinned` frame to the connected client so it can auto-register
+	* the agent locally without the operator running `first-tree-hub agent add`.
+	*
+	* Best-effort: if the client is not currently connected to this server
+	* instance, the notification is silently dropped here — the client picks the
+	* pinning up on its next `client:register` handshake via the backfill path
+	* in `api/agent/ws-client.ts`.
+	*/
+	function notifyClientAgentPinned(agent) {
+		if (!agent.clientId) return;
+		const parsed = agentPinnedMessageSchema$1.safeParse({
+			type: "agent:pinned",
+			agentId: agent.uuid,
+			name: agent.name,
+			displayName: agent.displayName,
+			agentType: agent.type
+		});
+		if (!parsed.success) {
+			app.log.warn({
+				err: parsed.error.flatten(),
+				agentId: agent.uuid,
+				clientId: agent.clientId
+			}, "agent:pinned frame failed schema validation — not sending");
+			return;
+		}
+		sendToClient(agent.clientId, parsed.data);
+	}
 	const listAgentsFilterSchema = z.object({ type: agentTypeSchema$1.optional() });
 	app.get("/", async (request) => {
 		const query = paginationQuerySchema.parse(request.query);
@@ -6146,6 +6518,7 @@ async function adminAgentRoutes(app) {
 			source: body.source ?? "admin-api",
 			managerId
 		});
+		notifyClientAgentPinned(agent);
 		return reply.status(201).send({
 			...agent,
 			createdAt: agent.createdAt.toISOString(),
@@ -6158,7 +6531,9 @@ async function adminAgentRoutes(app) {
 		const body = updateAgentSchema.parse(request.body);
 		const member = requireMember(request);
 		if (body.managerId !== void 0 && member.role !== "admin") throw new ForbiddenError("Only admins can reassign an agent's manager");
+		const before = body.clientId !== void 0 ? await getAgent(app.db, request.params.uuid) : null;
 		const agent = await updateAgent(app.db, request.params.uuid, body);
+		if (before && before.clientId === null && agent.clientId !== null) notifyClientAgentPinned(agent);
 		return {
 			...agent,
 			createdAt: agent.createdAt.toISOString(),
@@ -8551,6 +8926,32 @@ function clientWsRoutes(notifier, instanceId) {
 							type: "client:registered",
 							clientId: data.clientId
 						}));
+						try {
+							const pinned = await listActiveAgentsPinnedToClient(app.db, data.clientId);
+							for (const agent of pinned) {
+								const parsed = agentPinnedMessageSchema$1.safeParse({
+									type: "agent:pinned",
+									agentId: agent.uuid,
+									name: agent.name,
+									displayName: agent.displayName,
+									agentType: agent.type
+								});
+								if (!parsed.success) {
+									app.log.warn({
+										err: parsed.error.flatten(),
+										agentId: agent.uuid,
+										clientId: data.clientId
+									}, "agent:pinned backfill frame failed schema validation — skipping");
+									continue;
+								}
+								socket.send(JSON.stringify(parsed.data));
+							}
+						} catch (err) {
+							app.log.error({
+								err,
+								clientId: data.clientId
+							}, "agent:pinned backfill on client:register failed — client may need manual `agent add`");
+						}
 					} else if (type === "agent:bind") {
 						if (!clientId) {
 							socket.send(JSON.stringify({