feat: add agent reset flow and document machine handover

convex/machines.ts

@@ -1634,6 +1634,53 @@ export const toggleActive = mutation({
   },
 })
 
+export const resetAgent = mutation({
+  args: {
+    machineId: v.id("machines"),
+    actorId: v.id("users"),
+  },
+  handler: async (ctx, { machineId, actorId }) => {
+    const machine = await ctx.db.get(machineId)
+    if (!machine) {
+      throw new ConvexError("Máquina não encontrada")
+    }
+
+    const actor = await ctx.db.get(actorId)
+    if (!actor || actor.tenantId !== machine.tenantId) {
+      throw new ConvexError("Acesso negado ao tenant da máquina")
+    }
+    const normalizedRole = (actor.role ?? "AGENT").toUpperCase()
+    const STAFF = new Set(["ADMIN", "MANAGER", "AGENT"])
+    if (!STAFF.has(normalizedRole)) {
+      throw new ConvexError("Apenas equipe interna pode resetar o agente da máquina")
+    }
+
+    const tokens = await ctx.db
+      .query("machineTokens")
+      .withIndex("by_machine", (q) => q.eq("machineId", machineId))
+      .collect()
+
+    const now = Date.now()
+    let revokedCount = 0
+    for (const token of tokens) {
+      if (!token.revoked) {
+        await ctx.db.patch(token._id, {
+          revoked: true,
+          expiresAt: now,
+        })
+        revokedCount += 1
+      }
+    }
+
+    await ctx.db.patch(machineId, {
+      status: "unknown",
+      updatedAt: now,
+    })
+
+    return { machineId, revoked: revokedCount }
+  },
+})
+
 type RemoteAccessEntry = {
   id: string
   provider: string